📘 תיעוד 193

הפניה ל-Agent SDK: TypeScript

הפניה מלאה ל-API של Agent SDK ל-TypeScript, כולל כל הפונקציות, הטיפוסים והממשקים.

#התקנה

npm install @anthropic-ai/claude-agent-sdk

[!NOTE]

ה-SDK אורז בינארי מקורי של Claude Code עבור הפלטפורמה, כתלות אופציונלית, לדוגמה @anthropic-ai/claude-agent-sdk-darwin-arm64. ברוב ההתקנות אין צורך בהתקנה נפרדת של Claude Code. גרסת ה-SDK עוקבת אחרי גרסת Claude Code הארוזה יחד איתו. SDK v0.3.191 אורז את Claude Code v2.1.191, ולכן תכונה בדף הזה שדורשת גרסת Claude Code זקוקה למהדורת SDK עם אותו מספר patch, או למהדורה מאוחרת יותר. אם מנהל החבילות מדלג על תלויות אופציונליות, ה-SDK זורק Native CLI binary for <platform>-<arch> not found. הגדירו את pathToClaudeCodeExecutable לבינארי claude שהותקן בנפרד.

אם מנהל החבילות לא מיישם את שדה libc של npm, כמו ש-Yarn 1.x לא עושה זאת, בלינוקס מתקבלות גם חבילת הפלטפורמה של glibc וגם זו של musl, וגודל ההתקנה גדל בערך פי שניים. ב-Agent SDK v0.2.141 ומעלה, ה-SDK עדיין מפעיל את הווריאנט הנכון. כדי לשחרר את המקום בתמונת קונטיינר, מחקו את חבילת הפלטפורמה שלא תואמת ל-libc שבו האפליקציה רצה. עבור סביבת ריצה של glibc על x64, זו הפקודה rm -rf node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl. במכונת פיתוח המחיקה זמנית, כי Yarn מתקין מחדש את החבילה בשינוי התלויות הבא.

#קימפול לקובץ הפעלה יחיד

כשמקמפלים את האפליקציה לקובץ הפעלה של קובץ יחיד עם bun build --compile, ה-SDK לא יכול לאתר את הבינארי של ה-CLI הארוז בזמן ריצה. require.resolve לא עובד בתוך מערכת הקבצים הווירטואלית $bunfs של קובץ ההפעלה המקומפל, ולכן ה-SDK זורק Native CLI binary for <platform>-<arch> not found.

כדי לעקוף זאת, הטמיעו את הבינארי של הפלטפורמה כנכס קובץ, חלצו אותו לנתיב אמיתי בהפעלה באמצעות extractFromBunfs(), והעבירו את הנתיב הזה ל-pathToClaudeCodeExecutable.

פונקציית העזר extractFromBunfs() דורשת @anthropic-ai/claude-agent-sdk v0.3.144 או מאוחר יותר. הדוגמה למטה בונה עבור macOS על Apple Silicon:

import binPath from "@anthropic-ai/claude-agent-sdk-darwin-arm64/claude" with { type: "file" };
import { extractFromBunfs } from "@anthropic-ai/claude-agent-sdk/extract";
import { query } from "@anthropic-ai/claude-agent-sdk";

const cliPath = extractFromBunfs(binPath);

for await (const message of query({
  prompt: "Hello",
  options: { pathToClaudeCodeExecutable: cliPath },
})) {
  console.log(message);
}

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

כל קובץ הפעלה מקומפל מטמיע בינארי של פלטפורמה אחת. התאימו את חבילת הפלטפורמה ב-import אל --target:

• כדי לבצע קומפילציה צולבת, התקינו את חבילת הפלטפורמה שאינה תואמת, לדוגמה npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force.
• ב-Windows, נתיב המשנה של הבינארי הוא claude.exe, לדוגמה @anthropic-ai/claude-agent-sdk-win32-x64/claude.exe.

#ייבוא נקודת הכניסה /core כשמאגדים את Agent SDK

אם האפליקציה מאגדת את Agent SDK יחד עם התלויות שלה, ייבאו מ-@anthropic-ai/claude-agent-sdk/core במקום משורש החבילה. נקודת הכניסה /core דורשת TypeScript Agent SDK v0.3.282 או מאוחר יותר, והטיפוסים שלה דורשים TypeScript 5.0 או מאוחר יותר.

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

• מיוצא: אותם query(), startup(), prewarm(), tool(), createSdkMcpServer() ו-resolveSettings() כמו בנקודת הכניסה של השורש, יחד עם הפונקציות שמשנות שם לסשנים, מתייגות סשנים ומוחקות סשנים, AbortError, קבועי זמן הריצה, וכל טיפוס. ייבוא prewarm() בגרסת alpha מ-/core דורש Agent SDK v0.3.314 או מאוחר יותר.
• הושמט: ייצואים של השורש, כולל המחלקה InMemorySessionStore והעזרים שמציגים רשימת סשנים, קוראים סשנים, מבצעים fork, מייבאים סשנים ומסכמים סשנים. אם צריך אחד מהם, השתמשו בנקודת הכניסה של השורש.

נקודת הכניסה של השורש כוללת בתוכה עותקים משלה של zod ושל @modelcontextprotocol/sdk. נקודת הכניסה /core מייבאת אותם מ-node_modules בטווחים שעליהם מצהירים peerDependencies של Agent SDK, ולכן באנדל שכבר כולל אותם לא נושא עותק שני. בתהליך נתון ייבאו מהשורש או מ-/core, ולא משניהם: אלה באנדלים נפרדים, וטעינה של שניהם נותנת שני עותקים של המחלקות ושל המצב של Agent SDK.

#פונקציות

#query()

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

function query({
  prompt,
  options
}: {
  prompt: string | AsyncIterable<SDKUserMessage>;
  options?: Options;
}): Query;

#פרמטרים

#ערך מוחזר

מחזיר אובייקט Query שמרחיב את AsyncGenerator<SDKMessage, void> עם מתודות נוספות.

#startup()

מחמם מראש את תהליך המשנה של ה-CLI על ידי הפעלתו (spawn) והשלמת לחיצת היד initialize לפני ש-prompt זמין. הידית WarmQuery המוחזרת מקבלת prompt מאוחר יותר וכותבת אותו לתהליך שכבר מוכן, כך שהקריאה הראשונה ל-query() נפתרת בלי לשלם בתוך הנתיב את עלות ה-spawn של תהליך המשנה ואת עלות האתחול. אם תיקיית העבודה של הסשן עדיין לא ידועה, השתמשו ב-prewarm().

function startup(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<WarmQuery>;

#פרמטרים

#ערך מוחזר

מחזיר Promise<WarmQuery> שנפתר אחרי שתהליך המשנה הופעל והשלים את לחיצת היד initialize.

מבין הודעות hook_progress ש-hook מסוג SessionStart או Setup פולט לפני השלמת לחיצת היד, מתקבלת רק החדשה ביותר, והיא נושאת את כל הפלט של ה-hook עד כה. startup() מחזיק את ההודעה הזו, את הודעת hook_started של ה-hook, וכל דבר אחר שתהליך המשנה פולט לפני השלמת לחיצת היד. ההודעות המוחזקות מגיעות אחרי קריאה ל-.query() על ה-WarmQuery ואיטרציה על התוצאה.

#דוגמה

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

import { startup } from "@anthropic-ai/claude-agent-sdk";

// Pay startup cost upfront
const warm = await startup({ options: { maxTurns: 3 } });

// Later, when a prompt is ready, this is immediate
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

#prewarm()

Alpha. מפעיל תהליך Claude Code כרזרבה לפני שידוע איזה סשן הוא ישרת, כדי לקשור אותו לסשן מאוחר יותר עם claim(). השתמשו בו באפליקציה שעולה לפני שהמשתמש בוחר תיקייה. דורש TypeScript Agent SDK v0.3.282 או מאוחר יותר.

prewarm() משלים את אותה לחיצת יד initialize כמו startup(), והתהליך ממתין ב-options.cwd כשמגדירים אותו, ואחרת בתיקייה זמנית פרטית תחת תיקיית ההגדרות של Claude Code. תיקיית העבודה של הסשן, ה-hooks של SessionStart, שרתי ה-MCP על stdio, וההקשר של CLAUDE.md ושל git ממתינים ל-claim. רזרבה מחזיקה בערך 230 עד 260 MB של זיכרון בזמן שהיא ממתינה. אם spawnClaudeCodeProcess מריץ את Claude Code במכונה אחרת או בקונטיינר, הגדירו את options.cwd לתיקייה שקיימת שם, כדי שהרזרבה תמתין בה.

function prewarm(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<SpareProcess>;

options ו-initializeTimeoutMs משמעותם זהה לזו שב-startup(), פרט לכך ש-options.cwd מגדיר רק את התיקייה שבה הרזרבה ממתינה. ה-promise נפתר עם SpareProcess אחרי שהתהליך השלים את לחיצת היד initialize. prewarm() זורק אם options מגדיר resume, continue או forkSession, כי לרזרבה עדיין אין סשן. כל מה ש-claim לא יכול להגדיר, כמו mcpServers, hooks, canUseTool, settingSources, systemPrompt ו-plugins, קבוע לכל חיי הרזרבה, ולכן שמרו רזרבה אחת לכל קבוצה נפרדת של האפשרויות האלה, והריצו prewarm() שוב כשהן משתנות.

#דוגמה

הריצו prewarm בעליית האפליקציה, ואז בצעו claim לרזרבה כשהמשתמש מתחיל סשן:

import { prewarm } from "@anthropic-ai/claude-agent-sdk";

// On application boot, before the session's folder is known
const spare = await prewarm({ options: { maxTurns: 3 } });

// Later, when the user starts a session in a folder
const claimedQuery = spare.claim({
  prompt: "What files are here?",
  options: { cwd: "/path/to/project" },
});

spare.claimed.catch((error: Error) => {
  // Unless the message starts with "option_not_applied", the prompt didn't run:
  // start this session with query() instead
  console.error("Claim failed:", error.message);
});

try {
  for await (const message of claimedQuery) {
    console.log(message);
  }
} catch (error) {
  // After a refused claim, the claimed query throws once it has yielded the error result
  console.error(`Session ended with an error: ${error}`);
}

#tool()

יוצר הגדרת כלי MCP בטוחה לטיפוסים, לשימוש עם שרתי MCP של ה-SDK.

function tool<Schema extends AnyZodRawShape>(
  name: string,
  description: string,
  inputSchema: Schema,
  handler: (args: InferShape<Schema>, extra: unknown) => Promise<CallToolResult>,
  extras?: { annotations?: ToolAnnotations; searchHint?: string; alwaysLoad?: boolean }
): SdkMcpToolDefinition<Schema>;

#פרמטרים

#ToolAnnotations

מוגדר ב-@modelcontextprotocol/sdk/types.js. כל השדות הם רמזים אופציונליים. לקוחות לא צריכים להסתמך עליהם לצורך החלטות אבטחה.

import { tool } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const searchTool = tool(
  "search",
  "Search the web",
  { query: z.string() },
  async ({ query }) => {
    return { content: [{ type: "text", text: `Results for: ${query}` }] };
  },
  { annotations: { readOnlyHint: true, openWorldHint: true } }
);

#createSdkMcpServer()

יוצר מופע של שרת MCP שרץ באותו תהליך כמו האפליקציה.

function createSdkMcpServer(options: {
  name: string;
  version?: string;
  instructions?: string;
  tools?: Array<SdkMcpToolDefinition<any>>;
  alwaysLoad?: boolean;
  timeout?: number;
}): McpSdkServerConfigWithInstance;

#פרמטרים

#listSessions()

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

function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;

#פרמטרים

#טיפוס מוחזר: SDKSessionInfo

#דוגמה

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

import { listSessions } from "@anthropic-ai/claude-agent-sdk";

const sessions = await listSessions({ dir: "/path/to/project", limit: 10 });

for (const session of sessions) {
  console.log(`${session.summary} (${session.sessionId})`);
}

#getSessionMessages()

קורא הודעות משתמש ועוזר מתמליל של סשן קודם.

function getSessionMessages(
  sessionId: string,
  options?: GetSessionMessagesOptions
): Promise<SessionMessage[]>;

#פרמטרים

#סוג החזרה: SessionMessage

#דוגמה

import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";

const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 });

if (latest) {
  const messages = await getSessionMessages(latest.sessionId, {
    dir: "/path/to/project",
    limit: 20
  });

  for (const msg of messages) {
    console.log(`[${msg.type}] ${msg.uuid}`);
  }
}

#getSessionInfo()

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

function getSessionInfo(
  sessionId: string,
  options?: GetSessionInfoOptions
): Promise<SDKSessionInfo | undefined>;

#פרמטרים

מחזיר SDKSessionInfo, או undefined אם הסשן לא נמצא.

#renameSession()

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

function renameSession(
  sessionId: string,
  title: string,
  options?: SessionMutationOptions
): Promise<void>;

#פרמטרים

#tagSession()

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

function tagSession(
  sessionId: string,
  tag: string | null,
  options?: SessionMutationOptions
): Promise<void>;

#פרמטרים

#forkSession()

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

function forkSession(
  sessionId: string,
  options?: ForkSessionOptions
): Promise<ForkSessionResult>;

#פרמטרים

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

forkSession() זורק כאשר:

• sessionId אינו UUID
• הסשן לא נמצא, או שאין בו הודעות
• upToMessageId לא תואם לאף הודעה בתמליל

#resolveSettings()

פותר את הגדרות Claude Code האפקטיביות לתיקייה נתונה באמצעות אותו מנוע מיזוג כמו ה CLI, בלי ליצור תהליך של Claude CLI. השתמשו בזה כדי לבדוק איזו תצורה קריאה ל query() הייתה רואה לפני שמפעילים קריאה.

[!NOTE]

הפונקציה הזו באלפא וה API שלה עשוי להשתנות לפני ייצוב.

הצילום שונה ממה שסשן query() חי מחיל:

• policyHelper: resolveSettings() קורא מקורות MDM, כולל plist של macOS ו HKLM/HKCU של Windows, אבל לא מריץ את תהליך המשנה policyHelper שהוגדר על ידי המנהל.
• הגדרות מנוהלות שרת: resolveSettings() לא מביא הגדרות מנוהלות שרת. העבירו אותן כ options.serverManagedSettings כדי לכלול אותן.
• defaultMode: הצילום מחזיר את permissions.defaultMode כמות שהוא מכל שכבה, ולכן הוא יכול לכלול את הערכים 'auto' ו 'bypassPermissions' מהגדרות פרויקט ומקומיות, שסשן חי מתעלם מהם.

function resolveSettings(
  options?: ResolveSettingsOptions
): Promise<ResolvedSettings>;

#פרמטרים

resolveSettings() מקבל אובייקט אפשרויות יחיד. כל השדות אופציונליים.

#סוג החזרה: ResolvedSettings

resolveSettings() מחזיר אובייקט שמתאר את ההגדרות הממוזגות ואת המקור שתרם כל מפתח.

#דוגמה

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

import { resolveSettings } from "@anthropic-ai/claude-agent-sdk";

const { effective, provenance } = await resolveSettings({
  cwd: "/path/to/project",
  settingSources: ["user", "project", "local"],
});

console.log(`Cleanup period: ${effective.cleanupPeriodDays} days`);
console.log(`Set by: ${provenance.cleanupPeriodDays?.source}`);

#טיפוסים

#Options

אובייקט תצורה לפונקציה query().

#טיפול בתגובות API איטיות או תקועות

תהליך המשנה של ה-CLI קורא כמה משתני סביבה ששולטים בזמן המתנה ל-API ובזיהוי תקיעה. העבירו אותם דרך האפשרות env:

import { query } from "@anthropic-ai/claude-agent-sdk";

const result = query({
  prompt: "Analyze this code",
  options: {
    env: {
      ...process.env,
      API_TIMEOUT_MS: "120000",
      CLAUDE_CODE_MAX_RETRIES: "2",
      CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: "120000",
    },
  },
});

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

• CLAUDE_CODE_MAX_RETRIES: מספר מרבי של ניסיונות API חוזרים. ברירת המחדל 10, עם תקרה של 15. לכל ניסיון חוזר יש חלון API_TIMEOUT_MS משלו.

  להרצות ללא השגחה שצריכות להמתין לאורך השבתות ארוכות יותר, הגדירו CLAUDE_CODE_RETRY_WATCHDOG=1: זה מנסה שוב שגיאות קיבולת חולפות ללא הגבלה, וב-Claude Code מגרסה v2.1.199 ואילך מעלה את ברירת המחדל לשגיאות חולפות אחרות ל-300 ומסיר את התקרה על המשתנה הזה.

• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: watchdog לתקיעה של סוכני משנה. כש-watchdog הזרם פועל, ברירת המחדל היא CLAUDE_STREAM_IDLE_TIMEOUT_MS ועוד 5 דקות, כלומר 600000 אלא אם מעלים את המשתנה הזה. כש-watchdog הזרם כבוי, ברירת המחדל היא 600000. לפני v2.1.257, ברירת המחדל הייתה תמיד 600000.

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

• CLAUDE_ENABLE_STREAM_WATCHDOG עם CLAUDE_STREAM_IDLE_TIMEOUT_MS: watchdog לזרם שמבטל את הבקשה כשהכותרות כבר הגיעו אבל גוף התגובה מפסיק לזרום. ה-watchdog פועל כברירת מחדל לכל הספקים. הגדירו CLAUDE_ENABLE_STREAM_WATCHDOG=0 כדי לכבות אותו. CLAUDE_STREAM_IDLE_TIMEOUT_MS ברירת המחדל שלו 300000 והוא נחתך למינימום הזה. אחרי הביטול, ניסיונות חוזרים אוטומטיים מכסים את מה ש-Claude Code עושה, לפי כמה רחוק התגובה התקדמה.

  בזמן שה-watchdog ממתין לתגובה ששער מאחורי ANTHROPIC_BASE_URL מחזיק פתוחה עם פינגים של keep-alive, מארח שמגדיר את includePartialMessages ממשיך לקבל אירועי זרם ping מסוג stream events, ולכן קראו את המסגרות האלה כסימן שהחיבור חי, במקום למדוד timeout לסשן על שתיקה. לפני v2.1.257, המסגרות נפסקו 5 דקות אחרי אירוע הזרם האמיתי האחרון.

#אובייקט Query

ממשק שמוחזר על ידי הפונקציה query().

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<SDKControlInterruptResponse | undefined>;
  rewindFiles(
    userMessageId: string,
    options?: { dryRun?: boolean }
  ): Promise<RewindFilesResult>;
  setPermissionMode(mode: PermissionMode): Promise<void>;
  setModel(model?: string): Promise<void>;
  setMaxThinkingTokens(maxThinkingTokens: number | null): Promise<void>;
  applyFlagSettings(settings: {
    [K in keyof Settings]?: K extends 'effortLevel'
      ? 'low' | 'medium' | 'high' | 'xhigh' | 'max' | null
      : Settings[K] | null;
  }): Promise<void>;
  updateSettings(
    source: 'localSettings' | 'userSettings',
    settings: Record<string, unknown>,
  ): Promise<void>;
  initializationResult(): Promise<SDKControlInitializeResponse>;
  reinitialize(): Promise<SDKControlInitializeResponse>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  supportedAgents(): Promise<AgentInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  getContextUsage(opts?: {
    detail?: 'summary' | 'full';
  }): Promise<SDKControlGetContextUsageResponse>;
  readFile(
    path: string,
    options?: { maxBytes?: number; encoding?: 'utf-8' | 'base64' }
  ): Promise<SDKControlReadFileResponse | null>;
  reloadPlugins(options?: {
    holdOnCacheImpact?: boolean;
    addPlugins?: SdkPluginConfig[];
  }): Promise<SDKControlReloadPluginsResponse>;
  reloadSkills(): Promise<SDKControlReloadSkillsResponse>;
  reloadOutputStyles(): Promise<SDKControlReloadOutputStylesResponse>;
  seedReadState(path: string, mtime: number): Promise<void>;
  accountInfo(): Promise<AccountInfo>;
  reconnectMcpServer(serverName: string): Promise<void>;
  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
  setMcpPermissionModeOverride(
    serverName: string,
    mode: 'default' | 'auto' | null
  ): Promise<{ warning?: string }>;
  readMcpResource(serverName: string, uri: string): Promise<SDKControlMcpReadResourceResponse>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  backgroundTasks(toolUseId?: string): Promise<boolean>;
  close(): void;
}

#מתודות

#setMcpPermissionModeOverride()

דורס את מצב ההרשאות לכלים של שרת MCP אחד במצב מחמיר יותר מזה של הסשן, או מנקה את הדריסה עם null. השתמשו בזה כשסשן רץ במצב שמדלג על הנחיות לכל פעולה, אבל הכלים של שרת אחד עדיין צריכים להיבדק. דורש TypeScript SDK מגרסה v0.3.187 ואילך.

העבירו אחד משלושה ערכים כ-mode:

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

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

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

זמין רק במצב קלט בסטרימינג, אותה מגבלה כמו setModel() ו-setPermissionMode().

#seedReadState()

מסמן קובץ כקובץ שכבר נקרא כדי ש-Edit מאוחר יותר לא ייכשל עם File has not been read yet. השתמשו בזה כשהיישום הסיר תוצאת Read קודמת מהקשר השיחה ו-Claude יערוך את הקובץ הזה בהמשך. דורש TypeScript SDK מגרסה v0.2.83 ואילך.

העבירו את mtime כזמן השינוי של הקובץ ברגע הקריאה הקודמת ההיא, באלפיות שנייה שלמות מאז ה-epoch, לדוגמה Math.floor(stat.mtimeMs). אם הקובץ בדיסק השתנה אחרי הזמן הזה, Claude Code מדלג על הסימון.

ה-promise נפתר בין אם הקובץ סומן ובין אם לא, ולכן promise שנפתר לא אומר איזו מהאפשרויות קרתה.

#backgroundTasks()

מעביר את פקודות Bash וסוכני המשנה הרצים, שהתור ממתין להם, לרקע, כמו לחיצה על Ctrl+B בטרמינל האינטראקטיבי. העבירו את toolUseId של קריאת כלי כדי להעביר לרקע רק את פקודת Bash או סוכן המשנה שהקריאה הזו התחילה, או השמיטו אותו כדי להעביר לרקע כל משימת חזית. דורש TypeScript SDK מגרסה v0.2.139 ואילך.

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

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

• true: משימה הועברה לרקע, או שהשמטתם את toolUseId.
• false: ה-toolUseId שהעברתם לא התאים לאף משימת חזית.

אם משימות רקע מושבתות לסשן, למשל עם CLAUDE_CODE_DISABLE_BACKGROUND_TASKS, ה-promise נדחה במקום זאת ושום דבר לא מועבר לרקע.

#applyFlagSettings()

משנה הגדרות בסשן פעיל בלי להפעיל מחדש את השאילתה. השתמשו בזה כשהגדרה שאין לה setter ייעודי צריכה להשתנות באמצע הסשן, למשל הידוק permissions אחרי שהסוכן קורא קלט לא מהימן. setModel() ו-setPermissionMode() הם setters ייעודיים לשני המפתחות האלה. applyFlagSettings() הוא הצורה הכללית שמקבלת כל תת קבוצה של מפתחות ההגדרות, והעברת model כאן מתנהגת כמו setModel().

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

• מוחל בתור הבא: ultracode, permissions, hooks, skillOverrides, fastMode, agent. החלפת agent מחילה גם את דריסת המודל ואת ה-hooks של אותו סוכן בתור הבא. הנחיית המערכת שלו חלה בתור הבא. בסשן שמשתמש מחדש בהנחיית מערכת מוקלטת, היא חלה אחרי שהסשן נדחס.
• מוחל במהלך התור הנוכחי: model. אם מחליפים את model בזמן שקלוד עובד על תור, התשובה שקלוד כבר מייצר מסתיימת במודל הישן, ושאר התור, החל מהקריאה הבאה ש-Claude Code עושה למודל, משתמש בחדש. סוכני משנה שומרים על המודל שלהם. לפני v2.1.212, החלפה באמצע תור המתינה לתור הבא.
• מוחל עד התור הבא: effortLevel. הרמה חלה מהקריאה הבאה של Claude Code למודל. אם שינוי רמת המאמץ שומר על מטמון ההנחיה, כמו ב-Claude Opus 5.5 עם מפתח API או מנוי Claude, צפו שהיא תחול בתור הבא.
• בלי השפעה באמצע הסשן: אפשרויות הנחיית המערכת. הן נפתרות פעם אחת בהפעלה, ולכן הסשן הפעיל שומר על הערך המקורי גם כשהקריאה מצליחה. כדי לשנות אותן, התחילו סשן חדש.

effortLevel מקבל שם של רמת מאמץ. הוא גם מקבל "ultracode", שמבקש מאמץ xhigh עם ultracode מופעל. applyFlagSettings() מצהיר על effortLevel בלי הערך הזה, ולכן ב-TypeScript העבירו { ultracode: true, effortLevel: "xhigh" } לאותה תוצאה, או את מפתח ultracode לבד כדי להפעיל ultracode ברמת המאמץ הנוכחית של הסשן. הערך ultracode דורש Claude Code v2.1.203 או מאוחר יותר, ומתקבל רק על ידי applyFlagSettings(), לא על ידי מפתח effortLevel בקובץ הגדרות. לפני v2.1.284, מפתח ultracode לבד גם קבע את הרמה ל-xhigh.

הערכים נכתבים לשכבת flag-settings, וממוזגים מעל מה שאפשרות settings המוטמעת של query() קבעה בהפעלה. זו אותה שכבה שקטע הקדימות בעמוד קורא לה אפשרויות פרוגרמטיות. effortLevel הוא חריג: הרמה שאתם מעבירים מחליפה רמה מ---effort או מהגדרות, כולל הגדרות מנוהלות, כפי שסדר פתרון המאמץ מראה.

קריאות עוקבות ממזגות באופן רדוד מפתחות ברמה העליונה. קריאה שנייה עם { permissions: {...} } מחליפה את כל אובייקט permissions מהקריאה הקודמת במקום למזג אותו מיזוג עמוק.

כדי לנקות מפתח שקבעתם עם applyFlagSettings(), העבירו null למפתח הזה. רוב המפתחות אז חוזרים קודם לערך שאפשרות settings של query() קבעה בהפעלה, ואחר כך למקורות בקדימות נמוכה יותר. model שנוקה מתאפס למודל ברירת המחדל של Claude Code, גם כשקובץ הגדרות קובע model. העברת undefined לא משפיעה כי סריאליזציה של JSON משמיטה אותו.

שלושה מפתחות מלבד model מאפסים את מצב הסשן במקום לחזור אחורה:

• effortLevel: null מחזיר את הסשן לרמת המאמץ ברירת המחדל של המודל, לא לאפשרות effort של query() או ל-effortLevel מקובץ הגדרות.
• agent: null מריץ את השרשור הראשי בלי סוכן, החל מהתור הבא, במקום לשחזר את אפשרות agent של query() או agent מקובץ הגדרות. אם הסוכן שנוקה החיל מודל משלו, הסשן חוזר למודל שהוא פתר בהפעלה.
• ultracode: null מכבה את ultracode, כמו ש-false עושה, במקום לשחזר ערך ultracode מקובץ הגדרות. הסשן שומר על רמת המאמץ הנוכחית שלו, אז העבירו effortLevel באותה קריאה כדי לשנות אותה.

זמין רק במצב קלט בזרימה, אותה מגבלה כמו setModel() ו-setPermissionMode().

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

import { query } from "@anthropic-ai/claude-agent-sdk";

const q = query({ prompt: messageStream });

// Override the model for the rest of the session
await q.applyFlagSettings({ model: "claude-opus-4-6" });

// Later: clear the override; the model resets to Claude Code's default
await q.applyFlagSettings({ model: null });

[!NOTE]

applyFlagSettings() הוא TypeScript בלבד. ה-Python SDK לא חושף מתודה מקבילה.

#updateSettings()

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

• "localSettings": מקבל outputStyle וממזג אותו אל קובץ ההגדרות המקומי של הפרויקט, .claude/settings.local.json. הסגנון החדש נכנס לתוקף בבקשה הבאה של הסשן.
• "userSettings": מקבל effortLevel ושומר אותו כרמת המאמץ ברירת המחדל למודל הנוכחי של הסשן, תחת modelSettings בקובץ הגדרות המשתמש שלכם. העברת max לא כותבת דבר, כי max הוא לסשן בלבד. הסשן הפעיל שומר על רמת המאמץ הנוכחית שלו בכל מקרה, אז קראו ל-applyFlagSettings() כשאתם רוצים גם לשנות אותה. המקור הזה דורש TypeScript SDK v0.3.277 או מאוחר יותר, שכולל את Claude Code v2.1.277.

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

#toggleMcpServer()

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

• שרת stdio, SSE או HTTP שהוספתם באמצע הסשן עם setMcpServers(): הסרת הכלים שלו דורשת Claude Code v2.1.285 או מאוחר יותר.
• שרת בתוך התהליך שיצרתם עם createSdkMcpServer(), בין שהעברתם אותו ב-mcpServers ובין שבאמצעות setMcpServers(): ניתוקו והסרת הכלים שלו דורשים Claude Code v2.1.286 או מאוחר יותר. השבתה של אחד גם מכשילה את קריאות הכלים שלו שעדיין רצות, כך שקלוד מקבל תוצאת שגיאה לכל אחת מהן מיד, בלי להמתין שה-handler שלכם יחזור.

#WarmQuery

Handle שמוחזר על ידי startup(). תת התהליך כבר הופעל ואותחל, ולכן קריאה ל-query() על ה-handle הזה כותבת את ההנחיה ישירות לתהליך שמוכן, בלי השהיית הפעלה.

interface WarmQuery extends AsyncDisposable {
  query(prompt: string | AsyncIterable<SDKUserMessage>): Query;
  close(): void;
}

#מתודות

WarmQuery מממש AsyncDisposable, ולכן אפשר להשתמש בו עם await using לניקוי אוטומטי.

#SpareProcess

אלפא. Handle שמוחזר על ידי prewarm(): תהליך Claude Code שהופעל, שעדיין לא קשור לסשן, ואפשר לתבוע אותו פעם אחת. דורש TypeScript Agent SDK v0.3.282 או מאוחר יותר.

interface SpareProcess extends AsyncDisposable {
  claim(params: {
    prompt: string | AsyncIterable<SDKUserMessage>;
    options: ClaimOptions;
  }): Query;
  readonly claimed: Promise<{ cwd: string; sessionId: string; parkedMs?: number; sdkMcpSettled: boolean }>;
  readonly exited: Promise<void>;
  close(): void;
}

#חברים

options.cwd נדרש. תביעה יכולה גם לקבוע additionalDirectories, model, permissionMode, maxThinkingTokens, שכבת על של flag-settings ב-settings, appendSystemPrompt, title, agents, ואסימונים לכל סשן ב-env.

Claude Code יכול לסרב לתביעה, למשל לתיקייה שלא קיימת או לתיקייה שהגדרות הפרויקט שלה קובעות env, agent או model. אחרי סירוב, הנחיה ש-claim() כבר שלח מקבלת תוצאת שגיאה שהטקסט שלה מתחיל ב-not_claimed, והשאילתה שהוחזרה זורקת אחר כך. עטפו את הלולאה של השאילתה בבלוק try כדי להמשיך מעבר לזריקה. כש-claimed נדחה עם הודעה שמתחילה ב-option_not_applied, הסשן רץ בלי ה-model או ה-maxThinkingTokens שביקשתם. אחרי כל דחייה אחרת ההנחיה שלכם לא רצה, אז התחילו את הסשן עם query().

#SDKControlInitializeResponse

טיפוס ההחזרה של initializationResult(). מכיל נתוני אתחול של הסשן.

type SDKControlInitializeResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  output_style: string;
  available_output_styles: string[];
  models: ModelInfo[];
  account: AccountInfo;
  fast_mode_state?: "off" | "cooldown" | "on";
  fast_mode_disabled_reason?: FastModeDisabledReason;
  hooks_applied?: boolean;
  sdk_mcp_manifests_parked?: Record<
    string,
    | "parked"
    | "already_connected"
    | "protocol_version_mismatch"
    | "malformed"
    | "not_honoured"
  >;
  claude_code_version?: string;
};

hooks_applied מדווח אם Claude Code רשם את ה-hooks שבקשת initialize נשאה. ה-SDK שולח את הבקשה הזו פעם אחת כשהסשן מתחיל, ושוב בכל קריאה ל-reinitialize(). השדה דורש Agent SDK v0.3.238 או מאוחר יותר.

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

• true: Claude Code רשם את ה-hooks. ה-initialize הראשון של סשן מחזיר את הערך הזה. initialize חוזר שנשלח דרך stdin של ה-CLI גם מחזיר true. במקרה הזה ה-hooks בבקשה החדשה מחליפים את ה-hooks שנרשמו קודם.
• false: Claude Code התעלם מה-hooks. initialize חוזר שנשלח לסשן מרוחק מחזיר את הערך הזה, כך שלקוח שני שמצטרף לסשן לא יכול להחליף את ה-hooks שהלקוח הראשון רשם.

לפני Agent SDK v0.3.238, התשובה מעולם לא נשאה את השדה, ו-Claude Code התעלם מ-hooks בכל initialize חוזר.

שדה sdkMcpServerManifests של הבקשה ושדה sdk_mcp_manifests_parked של התשובה מיועדים לשרתי SDK MCP בתוך התהליך שיצרתם עם createSdkMcpServer(). האפליקציה שלכם לא קובעת ולא קוראת אף אחד משני השדות.

claude_code_version הוא גרסת Claude Code של התהליך שמריץ את התורים של הסשן. זה אותו ערך שהודעת האתחול SDKSystemMessage נושאת, כך שאפשר לקרוא את גרסת ה-CLI לפני התור הראשון.

• השדה דורש Agent SDK v0.3.296 או מאוחר יותר, שכולל את Claude Code v2.1.296.
• אם השדה הוא undefined וקבעתם pathToClaudeCodeExecutable, כוונו אותו אל Claude Code v2.1.296 או מאוחר יותר.

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

מעטפת תשובת הבקרה של initialize מוצלח נושאת גם מערך pending_permission_requests. השדה נמצא על מעטפת התשובה עצמה, לא במטען SDKControlInitializeResponse שלמעלה. כל רשומה היא הודעת control_request מלאה עם אותה צורה { type: "control_request", request_id, request } שהסשן מזרים לבקשות הרשאה בזמן ריצה.

המערך מפרט את בקשות ההרשאה שתהליך Claude Code הזה הנפיק ועדיין לא פתר. ה-SDK קורא את המערך בשבילכם ומפנה כל רשומה ל-callback canUseTool שלכם, אותה מסירה חוזרת ש-reinitialize() מפעיל אחרי פער בתעבורה. טפלו במזהי בקשה שחוזרים באופן אידמפוטנטי, כי רשומה יכולה לחזור על בקשה שה-callback כבר קיבל לפני שהחיבור נותק.

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

#SDKControlInterruptResponse

קבלת ההפרעה: הערך ש-interrupt() נפתר אליו ב-CLI שמפרסם את היכולת interrupt_receipt_v1 ב-SDKSystemMessage.capabilities. דורש Claude Code v2.1.205 או מאוחר יותר. CLI מוקדמים יותר עונים להפרעה במטען הצלחה ריק, כך ש-interrupt() נפתר ל-undefined.

type SDKControlInterruptResponse = {
  still_queued: string[];
  cancelled?: string[];
};

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

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

פרשו את הרשימה עם ההסתייגויות האלה:

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

לקוח שמניע את פרוטוקול הבקרה של ה-CLI ישירות, במקום דרך interrupt(), יכול לקבוע cancel_queued: true על בקשת הבקרה interrupt. Claude Code v2.1.219 ומאוחר יותר מפרסם תמיכה עם היכולת interrupt_cancel_queued_v1 ב-SDKSystemMessage.capabilities. CLI ישנים יותר מתעלמים מהשדה ומשאירים הודעות שבתור לרוץ כרגיל. הפרעה כזו גם מבטלת כל הודעה שאחרת הייתה מפורטת תחת still_queued: הקבלה מפרטת אותן תחת cancelled, still_queued ריק, ואף אחת מהן לא רצה.

רשימת cancelled נושאת את אותן הסתייגויות כמו still_queued. המתודה interrupt() לעולם לא שולחת cancel_queued, ולכן קבלות שהיא נפתרת אליהן לא נושאות cancelled.

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

#SDKControlGetContextUsageResponse

טיפוס ההחזרה של getContextUsage(). עם ברירת המחדל detail, התשובה כוללת את המטען ש-Claude Code מציג עבור הפקודה /context בסשן אינטראקטיבי. לצד ספירות הטוקנים, המטען נושא שדות תצוגה כמו color ו-gridRows, ש-Claude Code משתמש בהם כדי לצייר את רשת השימוש של /context.

הארגומנט האופציונלי detail של המתודה בוחר איך Claude Code סופר כל קטגוריה. הארגומנט detail דורש Agent SDK מגרסה v0.3.257 ואילך.

• 'full': ברירת המחדל. Claude Code סופר כל קטגוריה באמצעות בקשות API לספירת טוקנים. הבקשות האלה לא מופיעות בזרם ההודעות, ולכן מעקב עלות שקורא את הזרם לא יראה אותן. ב-API של Anthropic אין חיוב על ספירת טוקנים.
• 'summary': העבירו { detail: 'summary' } כדי לקבל תשובה מהשימוש של התשובה האחרונה ומהערכות מקומיות במקום זאת. לא יוצאות בקשות לספירת טוקנים, והמספרים לכל קטגוריה משוערים.

כששולחים את /context כפרומפט במקום לקרוא למתודה, Claude Code מצרף מטען SDKContextUsage לשדה context_usage של הודעת העוזר שמספקת את התוצאה. השדה הזה דורש Agent SDK מגרסה v0.3.232 ואילך.

ב-SDKControlGetContextUsageResponse, השדות categories[].id, mcpInstructions, והשדות pluginId ו-path של רשומות agents ושל skills.skillFrontmatter דורשים Agent SDK מגרסה v0.3.304 ואילך.

type SDKControlGetContextUsageResponse = {
  categories: {
    id?:
      | "system_prompt"
      | "system_tools"
      | "mcp_tools"
      | "mcp_instructions"
      | "mcp_tools_deferred"
      | "system_tools_deferred"
      | "custom_agents"
      | "memory_files"
      | "skills"
      | "messages"
      | "autocompact_buffer"
      | "compact_buffer"
      | "free_space";
    name: string;
    tokens: number;
    color: string;
    isDeferred?: boolean;
    kind: "used" | "free" | "buffer" | "deferred";
  }[];
  totalTokens: number;
  maxTokens: number;
  rawMaxTokens: number;
  percentage: number;
  gridRows: {
    color: string;
    isFilled: boolean;
    categoryName: string;
    tokens: number;
    percentage: number;
    squareFullness: number;
  }[][];
  model: string;
  memoryFiles: {
    path: string;
    type: string;
    tokens: number;
  }[];
  mcpTools: {
    name: string;
    serverName: string;
    tokens: number;
    isLoaded?: boolean;
  }[];
  mcpInstructions?: {
    serverName: string;
    tokens: number;
  }[];
  deferredBuiltinTools?: {
    name: string;
    tokens: number;
    isLoaded: boolean;
  }[];
  systemTools?: {
    name: string;
    tokens: number;
  }[];
  systemPromptSections?: {
    name: string;
    tokens: number;
  }[];
  agents: {
    agentType: string;
    source: string;
    pluginId?: string;
    path?: string;
    tokens: number;
  }[];
  slashCommands?: {
    totalCommands: number;
    includedCommands: number;
    tokens: number;
  };
  skills?: {
    totalSkills: number;
    includedSkills: number;
    tokens: number;
    skillFrontmatter: {
      name: string;
      source: string;
      pluginName?: string;
      pluginId?: string;
      path?: string;
      tokens: number;
    }[];
  };
  autoCompactThreshold?: number;
  isAutoCompactEnabled: boolean;
  messageBreakdown?: {
    toolCallTokens: number;
    toolResultTokens: number;
    attachmentTokens: number;
    assistantMessageTokens: number;
    userMessageTokens: number;
    redirectedContextTokens: number;
    unattributedTokens: number;
    toolCallsByType: {
      name: string;
      callTokens: number;
      resultTokens: number;
    }[];
    attachmentsByType: {
      name: string;
      tokens: number;
    }[];
  };
  apiUsage: {
    input_tokens: number;
    output_tokens: number;
    cache_creation_input_tokens: number;
    cache_read_input_tokens: number;
  } | null;
};

קראו את ייחוס הטוקנים משדות האוסף:

• categories מחזיק את הסיכומים לכל קטגוריה. ה-kind של כל רשומה מסווג את השורה באותם ערכים כמו SDKContextUsageCategory. סווגו שורות לפי השדה הזה, ולא לפי name של התצוגה. השדה דורש Agent SDK מגרסה v0.3.268 ואילך.
• mcpTools ו-agents מייחסים טוקנים לכלי MCP בודדים ולסוכני משנה.
• memoryFiles מפרט כל קובץ זיכרון שנטען, עם העלות שלו.
• skills.skillFrontmatter מייחס את הטוקנים של רשימת המיומנויות לכל מיומנות שנכללה. הספירות לכל מיומנות מודדות את רשומת הרישום של כל מיומנות כפי ש-Claude Code באמת שולח אותה, והיא יכולה להיות קצרה יותר מה-frontmatter המלא של המיומנות. השוו את skills.totalSkills ל-skills.includedSkills כדי לראות אם כל מיומנות שהתגלתה נכנסה לרשימה.

totalTokens הוא שימוש ההקשר הנוכחי של הסשן, ו-maxTokens הוא החלון שלפיו נמדד השימוש הזה. החלון הזה הוא חלון ההקשר של המודל, או חלון הדחיסה האוטומטית הנמוך יותר כשאחד כזה חל. rawMaxTokens נושא את אותו ערך כמו maxTokens, ו-percentage הוא totalTokens כאחוז מעוגל של החלון הזה. apiUsage מחזיק את השימוש מתשובת ה-API האחרונה, לא סכום מצטבר של הסשן.

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

#מציאת שורה לפי מזהה, טוקני הוראות של שרת, או התוסף והקובץ של רשומה

הוראות שרת MCP הן הערות השימוש ששרתים מחוברים מספקים וש-Claude Code מוסיף להקשר, ושורה mcp_instructions של categories סופרת את הטוקנים שלהן. השתמשו בשדות האלה של getContextUsage() כדי לבחור שורת categories אחת לפי id, לפצל את טוקני mcp_instructions לפי שרת, או למצוא את התוסף והקובץ שמאחורי רשומת סוכן או מיומנות:

כדוגמה להתאמה לפי id, הדוגמה הזו מוצאת את שורת mcp_instructions:

// q is the Query object that query() returned
const usage = await q.getContextUsage();
// undefined if no connected server supplies instructions
const row = usage.categories.find((c) => c.id === "mcp_instructions");

#SDKControlReadFileResponse

טיפוס ההחזרה של readFile().

type SDKControlReadFileResponse = {
  contents: string;
  absPath: string;
  truncated?: boolean;
  encoding?: 'base64';
};

contents מחזיק את טקסט הקובץ, או נתוני base64 כשביקשתם encoding: 'base64'. במקרה הזה שדה encoding של התשובה מוגדר ל-'base64'. absPath הוא הנתיב המוחלט שנפתר. truncated מוגדר כשהקובץ היה ארוך יותר מתקרת maxBytes והתוכן נחתך בגבול הזה.

#מה readFile() יכול לקרוא

readFile() מגיש קבוצה מצומצמת יותר של קבצים מאשר כלי Read:

• קובץ רגיל בתוך אחת מתיקיות העבודה של הסשן, כמו cwd ו-additionalDirectories
• כמה מהקבצים של Claude Code עצמו עבור הסשן, כמו תוצאות כלים

כללי deny ו-ask של Read עדיין חוסמים נתיב תואם, וכלל allow רחב של Read לא פותח את שאר מערכת הקבצים ל-readFile(). לכל דבר אחר הקריאה נפתרת עם null.

#SDKControlReloadPluginsResponse

טיפוס ההחזרה של reloadPlugins().

type SDKControlReloadPluginsResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  plugins: {
    name: string;
    path: string;
    source?: string;
    version?: string;
  }[];
  mcpServers: McpServerStatus[];
  error_count: number;
  held?: boolean;
  cache_impact?: {
    mcp_servers_added: string[];
    mcp_servers_removed: string[];
    lsp_tool_change: ("adds" | "may-add" | "removes" | "may-remove") | null;
  };
};

שדות האוסף מתארים את הסשן אחרי הקריאה:

• commands, agents ו-mcpServers: הפקודות, סוכני המשנה וסטטוס שרתי ה-MCP של הסשן, באותן צורות ש-supportedCommands(), supportedAgents() ו-mcpServerStatus() מחזירות. supportedAgents() ממשיך להחזיר את הרשימה שנלכדה באתחול, ולכן קראו כאן את agents עבור הקבוצה שאחרי טעינה מחדש
• plugins: כל תוסף שנטען, עם ה-name שלו ו-path ההתקנה. version חוזר על מה שמניפסט התוסף מצהיר, והוא בשליטת מחבר התוסף, ולכן אמתו אותו לפני שסומכים עליו. הוא מושמט כשהמניפסט לא מצהיר על גרסה
• error_count: מספר השגיאות מטעינת התוספים

העבירו { holdOnCacheImpact: true } ל-reloadPlugins() כדי לעכב טעינה מחדש שתבטל את מטמון הפרומפט של השיחה, במקום להחיל אותה. Claude Code מריץ את הבדיקה שפקודת /reload-plugins האינטראקטיבית עושה לפני שהיא מזהירה על עלות המטמון. האפשרות דורשת Agent SDK מגרסה v0.3.268 ואילך. קובץ הרצה של Claude Code ישן מ-v2.1.268, כמו קובץ הרצה שאתם מפנים אליו את pathToClaudeCodeExecutable, מתעלם מהאפשרות ומחיל את הטעינה מחדש.

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

• true: הטעינה מחדש לא הוחלה, ושדות האוסף מתארים את הסשן כפי שהוא עדיין. cache_impact אומר מה ההחלה תשנה. כדי להחיל בכל זאת, קראו ל-reloadPlugins() שוב בלי האפשרות.
• false: הבדיקה לא מצאה השפעה על המטמון, והטעינה מחדש הוחלה.
• נעדר: לא העברתם את האפשרות, או שקובץ ההרצה של Claude Code ישן מ-v2.1.268 והחיל את הטעינה מחדש.

cache_impact נוכח רק לצד held: true. mcp_servers_added ו-mcp_servers_removed מציינים את שרתי ה-MCP של התוספים שהטעינה מחדש תרשום או תסיר, כשמות עם תחום בצורה plugin:<plugin>:<server>. השמות נכתבו על ידי מחבר התוסף, ולכן אמתו אותם לפני הצגתם. lsp_tool_change אומר אם ההחלה תוסיף או תסיר את כלי ה-LSP, או null כשהיא לא תעשה אף אחד מהשניים. הצורות may- אומרות שהבדיקה לא יכלה לראות במלואה את קבוצת התוספים הממתינה.

#טעינת תיקיות תוספים נוספות עם addPlugins

כדי לטעון תיקיות תוספים שלא היו באפשרות plugins בעת ההפעלה, העבירו אותן ל-reloadPlugins() בתור addPlugins, רשימה של רשומות SdkPluginConfig שה-path שלהן מוחלט. Claude Code טוען את התיקיות החדשות וטוען מחדש את התוספים הקיימים של הסשן במעבר אחד. שרתי ה-MCP של כל תוסף שנוסף מתחברים גם הם, אלא אם הגדרתם skipMcpDiscovery על רשומת התיקייה הזו. דורש Agent SDK מגרסה v0.3.301 ואילך ו-Claude Code מגרסה v2.1.301 ואילך.

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

const result = await q.reloadPlugins({
  addPlugins: [{ type: "local", path: "/opt/my-app/plugins/reports" }]
});

console.log(result.plugins.map((plugin) => plugin.path));

אם התיקייה נטענה, הרשימה המודפסת כוללת את /opt/my-app/plugins/reports, והפקודות וסוכני המשנה של התוסף מופיעים ב-result.commands וב-result.agents.

תיקייה שנוספה נשארת חלק מהסשן. כשקוראים ל-reloadPlugins() שוב, Claude Code טוען אותה מחדש עם שאר התוספים, ולא מעבירים אותה ב-addPlugins שוב.

#כש-reloadPlugins() לא טוען את תיקיות addPlugins

אם reloadPlugins() נדחה, אף אחת מתיקיות addPlugins לא מתווספת, ולכן העבירו אותן ב-addPlugins שוב כשמנסים מחדש. כשלדחייה יש אחד מהגורמים הבאים, הסשן שומר את התוספים שכבר היו לו:

• path יחסי או רשומה לא תקינה: הודעת השגיאה אומרת add_plugins must be a list of { type: "local", path } entries with absolute paths. Claude Code דוחה את כל הרשימה בגלל רשומה לא תקינה אחת, ולכן העבירו כל רשומה כ-{ type: "local", path } עם path מוחלט
• מנהל הפעיל את disableSideloadFlags בהגדרות המנוהלות שלכם: ההודעה אומרת reload_plugins add_plugins is disabled by managed settings (disableSideloadFlags). כדי לטעון את התיקייה, בקשו מהמנהל הזה להסיר את ההגדרה
• לא ניתן היה לבנות מחדש את הארגז החול: כשארגז החול פועל, Claude Code בונה מחדש את תצורת ארגז החול כדי שפקודות מעטפת בתוך ארגז החול לא יוכלו לכתוב לתיקיות שאתם מוסיפים. ההודעה אומרת the sandbox could not be rebuilt to keep shell commands out of this folder. בדקו שהגדרות ארגז החול שלכם עדיין מהוות תצורה תקינה

אם מעבירים holdOnCacheImpact והקריאה נפתרת עם held: true, תיקיות addPlugins לא מתווספות. כדי להוסיף אותן בכל זאת, קראו ל-reloadPlugins() שוב עם אותה רשימת addPlugins ובלי holdOnCacheImpact.

כשהקריאה נפתרת בלי held: true ותיקייה עדיין חסרה מ-result.plugins, התחילו בבדיקת הגורמים האלה:

• התיקייה לא קיימת או שהתוסף שלה נכשל בטעינה: result.error_count הוא 1 או גבוה יותר. התיקייה נשארת חלק מהסשן גם כך. אחרי שמתקנים את התיקייה, קראו ל-reloadPlugins() שוב כדי לטעון אותה, הפעם בלי לפרט אותה ב-addPlugins
• קובץ ההרצה של Claude Code ישן מ-v2.1.301: קובץ הרצה ישן מ-v2.1.301 מתעלם מ-addPlugins וטוען מחדש רק את התוספים שכבר היו לסשן. בדקו את claude_code_version בהודעת ה-init, והריצו קובץ הרצה בגרסה v2.1.301 או חדשה יותר

#SDKControlReloadSkillsResponse

טיפוס ההחזרה של reloadSkills().

type SDKControlReloadSkillsResponse = {
  skills: SlashCommand[];
};

skills מפרט את המיומנויות הזמינות אחרי הטעינה מחדש, באותה צורת SlashCommand ש-supportedCommands() מחזיר.

#SDKControlReloadOutputStylesResponse

טיפוס ההחזרה של reloadOutputStyles().

type SDKControlReloadOutputStylesResponse = {
  available_output_styles: string[];
};

available_output_styles מפרט את השמות של סגנונות הפלט המובנים והמותאמים הזמינים אחרי הטעינה מחדש.

#SDKControlMcpReadResourceResponse

טיפוס ההחזרה של readMcpResource(), שנושא את תוצאת resources/read של שרת ה-MCP. דורש TypeScript Agent SDK מגרסה v0.3.280 ואילך.

type SDKControlMcpReadResourceResponse = {
  contents: {
    uri: string;
    mimeType?: string;
    text?: string;
    blob?: string;
    _meta?: Record<string, unknown>;
  }[];
};

העבירו ל-readMcpResource() את שם השרת כפי ש-mcpServerStatus() מדווח אותו, ו-URI מסוג ui://, כמו ה-ui.resourceUri שכלי מצהיר ב-_meta שלו. הקריאה נדחית עבור כל סכמת URI אחרת, עבור שרת MCP של ה-SDK שהיישום שלכם מארח בעצמו, ועבור שרת שאינו מחובר. היא זמינה כש-capabilities של הודעת ה-init כוללות mcp_read_resource_v1.

כל רשומת contents היא פריט תוכן אחד כפי שהשרת שלח אותו, בלי מפתח _meta כלשהו תחת הקידומת com.anthropic/, השמורה ל-Claude Code. blob מחזיק נתוני base64 עבור פריט בינארי, ו-_meta הוא ה-_meta של הפריט עצמו, שבו שרת MCP Apps שם את ui.csp ו-ui.permissions של המשאב.

התוכן הוא HTML לא מהימן של צד שלישי, ולכן הציגו אותו בארגז חול.

#AgentDefinition

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

type AgentDefinition = {
  description: string;
  tools?: string[];
  disallowedTools?: string[];
  prompt: string;
  model?: string;
  mcpServers?: AgentMcpServerSpec[];
  skills?: string[];
  initialPrompt?: string;
  maxTurns?: number;
  autoCompactWindow?: number;
  background?: boolean;
  omitClaudeMd?: boolean;
  memory?: "user" | "project" | "local";
  effort?: "low" | "medium" | "high" | "xhigh" | "max" | number;
  permissionMode?: PermissionMode;
  criticalSystemReminder_EXPERIMENTAL?: string;
};

#AgentMcpServerSpec

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

type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;

כאשר McpServerConfigForProcessTransport הוא McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig.

#SettingSource

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

type SettingSource = "user" | "project" | "local";

#התנהגות ברירת מחדל

כש-settingSources מושמט או undefined, query() טוען את אותן הגדרות מערכת קבצים כמו Claude Code CLI: משתמש, פרויקט ומקומי. ראו מה settingSources לא שולט בו לגבי קלטים שנקראים בלי קשר לאפשרות הזו, ואיך להשבית אותם.

#למה להשתמש ב-settingSources

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

import { query } from "@anthropic-ai/claude-agent-sdk";

// Do not load user, project, or local settings from disk
const result = query({
  prompt: "Analyze this code",
  options: { settingSources: [] }
});

טעינת מקורות הגדרה מסוימים בלבד:

import { query } from "@anthropic-ai/claude-agent-sdk";

// Load only project settings, ignore user and local
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ["project"] // Only .claude/settings.json
  }
});

כדי לטעון הוראות פרויקט של CLAUDE.md, כללו את "project" ב-settingSources. ראו שינוי הנחיות מערכת לגבי האופן שבו טעינת CLAUDE.md פועלת עם אפשרויות הנחיית המערכת.

#עדיפות הגדרות

כשנטענים כמה מקורות, ההגדרות מתמזגות לפי העדיפות הזו (מהגבוהה לנמוכה):

1. הגדרות מקומיות (.claude/settings.local.json)
2. הגדרות פרויקט (.claude/settings.json)
3. הגדרות משתמש (~/.claude/settings.json)

אפשרויות תכנותיות כמו agents, allowedTools ו-settings דורסות הגדרות מערכת קבצים של משתמש, פרויקט ומקומי. אם הגדרת מדיניות מנוהלת ואפשרות תכנותית מגדירות את אותו מפתח, הערך המנוהל חל, עם חריגים כמו effortLevel שמועבר ל-applyFlagSettings().

#PermissionMode

type PermissionMode =
  | "default" // Standard permission behavior
  | "acceptEdits" // Auto-accept file edits
  | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt
  | "plan" // Planning mode - Claude explores and plans
  | "dontAsk" // Don't prompt for permissions, deny if not pre-approved
  | "auto"; // A model classifier reviews actions such as shell commands and network requests

#CanUseTool

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

הפונקציה מחליפה את בקשת ההרשאה האינטראקטיבית. ה-SDK קורא ל-canUseTool כשזרימת הערכת ההרשאות מגיעה לבקשה. קריאות שאושרו באחד מהאופנים האלה רצות בלי קריאה ל-canUseTool:

• קריאה שרשומת allowedTools או כלל allow בהגדרות מאשרת
• קריאה שמצב ההרשאות מאשר, כמו עריכת קובץ במצב acceptEdits

כדי לבדוק את הקריאות האלה, השתמשו ב-hook מסוג PreToolUse, שרץ גם עבורן.

כלל allow לא מאשר מראש את הפעולות שאף מצב לא מאשר אוטומטית. ראו איך הרשאות מוערכות לגבי אילו מהן מגיעות ל-callback ומה קורה במצב dontAsk ובמצב auto.

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    mcpServer?: { name: string; source: string };
    decisionReason?: string;
    defaultToNo?: boolean;
    suppressAlwaysAllowRule?: boolean;
    toolUseID: string;
    agentID?: string;
    requestId: string;
  }
) => Promise<PermissionResult | null>;

ה-callback בדרך כלל פותר את הבקשה על ידי החזרת PermissionResult, שה-SDK כותב בחזרה על התעבורה שלו כ-control_response. החזירו null רק כשהיישום שלכם כבר שלח את ה-control_response לבקשה הזו בערוץ שלו, תוך החזרת requestId. אז ה-SDK מדלג על כתיבת התשובה לתעבורה שלו. החזרת null בכל מקרה אחר משאירה את קריאת הכלי חסומה ללא הגבלת זמן, כי אף control_response לא נשלח ובקשות הרשאה לא פגות.

אפשרות requestId וערך ההחזרה null דורשים Claude Code גרסה v2.1.199 או חדשה יותר.

#PermissionResult

תוצאה של בדיקת הרשאה.

type PermissionResult =
  | {
      behavior: "allow";
      updatedInput?: Record<string, unknown>;
      updatedPermissions?: PermissionUpdate[];
      toolUseID?: string;
    }
  | {
      behavior: "deny";
      message: string;
      interrupt?: boolean;
      toolUseID?: string;
    };

אם מחזירים allow עם יותר מ-4,096 פריטים ב-updatedPermissions, Claude Code מתייחס לתוצאה כלא תקינה ודוחה את קריאת הכלי. כל עדכון נספר כפריט אחד, וכך גם כל רשומה ברשימת rules או directories שלו. הודעת הדחייה מסתיימת ב-updatedPermissions may hold at most 4096 updates, rules and directories in all. כדי שהקריאה תאושר, החזירו 4,096 פריטים או פחות.

#ToolConfig

הגדרה להתנהגות כלים מובנים.

type ToolConfig = {
  askUserQuestion?: {
    previewFormat?: "markdown" | "html";
  };
};

#McpServerConfig

הגדרה לשרתי MCP.

type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;

#McpStdioServerConfig

type McpStdioServerConfig = {
  type?: "stdio";
  command: string;
  args?: string[];
  env?: Record<string, string>;
};

#McpSSEServerConfig

type McpSSEServerConfig = {
  type: "sse";
  url: string;
  headers?: Record<string, string>;
};

#McpHttpServerConfig

type McpHttpServerConfig = {
  type: "http";
  url: string;
  headers?: Record<string, string>;
};

#McpSdkServerConfigWithInstance

הגדרה לשרת MCP בתוך התהליך. זה מה ש-createSdkMcpServer() מחזיר, בתוספת רשימת tools אופציונלית של רשומות McpServerToolPolicy שאתם מוסיפים.

type McpSdkServerConfigWithInstance = {
  type: "sdk";
  name: string;
  timeout?: number;
  tools?: McpServerToolPolicy[];
  instance: McpServer;
};

כדי לדרוש אישור לקריאות לאחד הכלים של השרת, או לדחות אותן, הוסיפו רשומת מדיניות שמציינת את הכלי. פרסו את מה ש-createSdkMcpServer() מחזיר לתוך אובייקט תחת mcpServers ושימו את הרשומה ברשימת tools על האובייקט הזה, כי אפשרות tools של הפונקציה מקבלת הגדרות כלים ולא רשומות מדיניות. רשימת המדיניות דורשת Agent SDK מגרסה v0.3.301 ואילך, ו-McpServerToolPolicy מתאר מה כל ערך של permission_policy עושה.

בסקריפט הזה, תו כללי ב-allowedTools מאשר מראש כל כלי בשרת records, אבל delete_record מסומן always_ask, ולכן קריאות אליו מגיעות בכל זאת אל canUseTool. עם הביאור destructiveHint: true, הקריאה עדיין מגיעה ל-callback אם הסשן רץ במצב auto, שבו ה-classifier של מצב auto היה יכול אחרת לאשר אותה.

import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";
import { z } from "zod";

const deleteRecord = tool(
  "delete_record",
  "Delete a customer record by ID",
  { id: z.string() },
  async ({ id }) => ({ content: [{ type: "text", text: `Deleted record ${id}` }] }),
  { annotations: { destructiveHint: true } }
);

const records = createSdkMcpServer({ name: "records", tools: [deleteRecord] });

for await (const message of query({
  prompt: "Delete customer record 42",
  options: {
    mcpServers: {
      // Spread the returned config and add the policy list beside it
      records: {
        ...records,
        tools: [{ name: "delete_record", permission_policy: "always_ask" as const }]
      }
    },
    allowedTools: ["mcp__records__*"],
    canUseTool: async (toolName, input) => {
      console.log(`Approval requested for ${toolName}`);
      return { behavior: "allow", updatedInput: input };
    }
  }
})) {
  if (message.type === "result" && message.subtype === "success") {
    console.log(message.result);
  }
}

כש-Claude קורא ל-delete_record, הסקריפט מדפיס Approval requested for mcp__records__delete_record.

כדי לשנות או להסיר מדיניות של כלי בזמן שהסשן רץ, העבירו את הגדרת השרת עם ערך tools חדש אל setMcpServers(). ערך tools שאתם מעבירים נכנס לתוקף מהקריאה הבאה של Claude לכלים של השרת הזה:

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

כללו בקריאה הזו את שאר השרתים בתוך התהליך וכל שרת שקריאה קודמת של setMcpServers() הוסיפה, אחרת הקריאה מנתקת אותם.

#McpServerToolPolicy

רשומה אחת ברשימת tools של McpSdkServerConfigWithInstance, שמציינת אחד הכלים של השרת וקובעת את מדיניות ההרשאה לקריאות לכלי הזה. הרשימה דורשת Agent SDK מגרסה v0.3.301 ואילך ו-Claude Code מגרסה v2.1.301 ואילך. קובץ הרצה ישן יותר של Claude Code, למשל קובץ הרצה שאתם מצביעים אליו ב-pathToClaudeCodeExecutable, מתעלם מהרשימה. אז always_ask ו-always_deny לא נאכפים, וכל קריאה עוברת דרך זרימת ההרשאות.

type McpServerToolPolicy = {
  name: string;
  permission_policy?: "always_allow" | "always_ask" | "always_deny";
  org_max_permission?: "allow" | "ask" | "blocked";
};

#ערכי permission_policy

בחרו always_ask כדי לאשר כל קריאה בעצמכם, או always_deny כדי לחסום את הכלי לגמרי:

• always_ask: כל קריאה לכלי צריכה אישור, גם אם רשומת allowedTools או כלל allow מכסה אותה. הקריאה מגיעה ל-callback של canUseTool או לכלי permissionPromptToolName, אלא אם היא הוכרעה קודם. mod בתוסף שאתם טוענים יכול לאשר אותה קודם. אחרת, במצב dontAsk היא נדחית, ובמצבי auto, plan ו-bypassPermissions אפשר לאשר אותה לפני שהיא מגיעה ל-callback שלכם
• always_deny: קריאה לכלי נדחית בכל מצב הרשאה, כולל bypassPermissions, אבל mod בתוסף שאתם טוענים עדיין יכול לאשר אותה

אם לא מעבירים canUseTool ולא permissionPromptToolName, או מגדירים את permissionPrompts ל-'none', קריאת always_ask שלא הוכרעה קודם נדחית אלא אם hook של PermissionRequest מאפשר אותה.

#מצבי הרשאה שיכולים לאשר קריאת always_ask

במצבי auto, plan ו-bypassPermissions, קריאה לכלי שמסומן always_ask יכולה להיות מאושרת לפני שהיא מגיעה ל-callback של canUseTool.

• auto: ה-classifier של מצב auto סוקר את הקריאה ויכול לאפשר אותה. כדי שכל קריאה תגיע ל-callback שלכם במצב auto, הגדירו destructiveHint: true ב-annotations של הכלי
• plan: בזמן שמצב auto זמין לסשן, קריאות לכלי always_ask עם הביאור readOnlyHint: true הולכות ל-classifier של מצב auto, שיכול לאפשר אותן. קריאות לכלי always_ask אחרים מגיעות ל-callback שלכם. כדי שגם קריאות של כלי לקריאה בלבד יגיעו ל-callback שלכם, הוסיפו destructiveHint: true ל-annotations של הכלי הזה לצד readOnlyHint: true. לחלופין, הגדירו את useAutoModeDuringPlan ל-false, מה שמכבה את ה-classifier בזמן תכנון
• bypassPermissions: כשמשתנה הסביבה CLAUDE_CODE_REMOTE הוא true, כמו בסשן ענן, הקריאה מאושרת בלי ה-callback שלכם, יהיו אשר יהיו הביאורים של הכלי. בכל מקום אחר הקריאה מגיעה ל-callback שלכם. כדי שהיא תגיע ל-callback שלכם גם בסשן ענן, הריצו את הסשן במצב default או acceptEdits במקום

הגדירו את destructiveHint ל-true במפורש במצבי auto ו-plan. לקריאות always_ask, Claude Code קורא destructiveHint שלא הוגדר בתור false, אף על פי שברירת המחדל שרשומה תחת ToolAnnotations היא true.

#McpClaudeAIProxyServerConfig

type McpClaudeAIProxyServerConfig = {
  type: "claudeai-proxy";
  url: string;
  id: string;
};

#SdkPluginConfig

הגדרה לטעינת תוספים ב-SDK.

type SdkPluginConfig = {
  type: "local";
  path: string;
  skipMcpDiscovery?: boolean;
};

דוגמה:

plugins: [
  { type: "local", path: "./my-plugin" },
  { type: "local", path: "/absolute/path/to/plugin" }
];

למידע מלא על יצירת תוספים ושימוש בהם, ראו Plugins.

#טיפוסי הודעות

#SDKMessage

טיפוס איחוד של כל ההודעות האפשריות שהשאילתה מחזירה.

type SDKMessage =
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage
  | SDKStatusMessage
  | SDKLocalCommandOutputMessage
  | SDKHookStartedMessage
  | SDKHookProgressMessage
  | SDKHookResponseMessage
  | SDKPluginInstallMessage
  | SDKToolProgressMessage
  | SDKAuthStatusMessage
  | SDKTaskNotificationMessage
  | SDKTaskStartedMessage
  | SDKTaskProgressMessage
  | SDKTaskUpdatedMessage
  | SDKBackgroundTasksChangedMessage
  | SDKThinkingTokensMessage
  | SDKSessionStateChangedMessage
  | SDKWorkerShuttingDownMessage
  | SDKCommandsChangedMessage
  | SDKNotificationMessage
  | SDKFilesPersistedEvent
  | SDKToolUseSummaryMessage
  | SDKMemoryRecallMessage
  | SDKRateLimitEvent
  | SDKElicitationCompleteMessage
  | SDKPermissionDeniedMessage
  | SDKPromptSuggestionMessage
  | SDKAPIRetryMessage
  | SDKControlRequestProgressMessage
  | SDKModelRefusalFallbackMessage
  | SDKModelRefusalNoFallbackMessage
  | SDKMirrorErrorMessage
  | SDKInformationalMessage
  | SDKConversationResetMessage;

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

• SDKControlRequestProgressMessage, subtype: "control_request_progress": מדווחת על התקדמות של בקשת בקרה ארוכה שהלקוח שלכם שלח. request_id מתאים את ההודעה לבקשה הזו, ו-status הוא "started" או "api_retry". דורש Agent SDK מגרסה v0.3.203 ואילך.
• SDKModelRefusalFallbackMessage, subtype: "model_refusal_fallback": נפלטת כשהמודל מסיים את הזרם בסירוב והתור מנוסה שוב על מודל גיבוי. נושאת original_model ו-fallback_model. דורש Agent SDK מגרסה v0.3.170 ואילך.
• SDKModelRefusalNoFallbackMessage, subtype: "model_refusal_no_fallback": נפלטת כשהמודל מסיים את הזרם בסירוב ולא רצה ניסיון חוזר, למשל כי לא מוגדר מודל גיבוי. נושאת original_model. דורש Agent SDK מגרסה v0.3.193 ואילך.

#SDKAssistantMessage

הודעת תשובה של העוזר.

type SDKAssistantMessage = {
  type: "assistant";
  uuid: UUID;
  session_id: string;
  message: BetaMessage; // From Anthropic SDK
  parent_tool_use_id: string | null;
  error?: SDKAssistantMessageError;
  aborted?: true;
  agent_id?: string;
  timestamp?: string;
  context_usage?: SDKContextUsage;
  usage_report?: SDKUsageReport;
  user_message_uuid?: string;
  user_message_uuids?: string[];
  resume_reason?: string;
};

השדה message הוא BetaMessage מ-Anthropic SDK. הוא כולל שדות כמו id, content, model, stop_reason ו-usage.

SDKAssistantMessageError הוא אחד מאלה: 'authentication_failed', 'oauth_org_not_allowed', 'account_on_hold', 'billing_error', 'rate_limit', 'overloaded', 'invalid_request', 'model_not_found', 'server_error', 'max_output_tokens', 'cloud_credential_error', או 'unknown'. ארבעה מהערכים האלה אומרים יותר ממה שהשמות שלהם אומרים:

• 'model_not_found': המודל שנבחר לא קיים או לא זמין לחשבון או לפריסה שלכם
• 'overloaded': ה-API החזיר 529 כי השרת בתפוסה מלאה, לעומת 'rate_limit', שהוא 429 מול המכסה שלכם
• 'account_on_hold': החשבון שלכם בהמתנה
• 'cloud_credential_error': Claude Code לא הצליח להשיג פרטי גישה שמישים של AWS או Google Cloud במכונה שהוא רץ עליה, ולכן שום בקשה לא הגיעה לספק הענן. הסיבה הרגילה היא כניסה לענן שפג תוקפה או שמעולם לא הושלמה במכונה הזו, אם כי שירות פרטי גישה שלא נגיש לזמן קצר מדווח על אותו ערך. ראו Could not load AWS or Google Cloud credentials. דורש TypeScript Agent SDK מגרסה v0.3.267 ואילך, שכולל את Claude Code מגרסה v2.1.267

aborted הוא true כשהפרעה או abort קיצרו את הודעת העוזר לפני שהזרם הושלם: להודעה אין stop_reason והתוכן עלול להסתיים באמצע מילה. השדה נעדר בהודעות שהושלמו כרגיל. הוא דורש Agent SDK מגרסה v0.3.214 ואילך.

agent_id מזהה את ה-subagent שיצר את ההודעה, והוא נעדר בהודעות של ה-thread הראשי. הערך שווה ל-task_id ב-task_started של אותו subagent ובאירועי משימה אחרים, והוא לא משתנה כשה-subagent ממשיך. בהודעות מ-subagent מקונן, הוא מציין את ה-subagent המקונן, לא את ה-subagent שהוליד אותו. השדה דורש Agent SDK מגרסה v0.3.292 ואילך.

התאימו הודעות של subagent לאירועי המשימה שלו לפי agent_id במקום לזווג את parent_tool_use_id של הודעה עם tool_use_id של אירוע משימה. כשקריאת כלי ממשיכה את ה-subagent, אירועי המשימה נושאים את tool_use_id של הקריאה הזו, בעוד ההודעות שומרות את parent_tool_use_id של קריאת הכלי שהתחילה את ה-subagent לראשונה, ולכן השניים כבר לא תואמים.

Claude Code מגדיר את user_message_uuid ואת user_message_uuids על הודעת העוזר הראשונה של התור, בתנאים שב-user_message_uuid. כשהתור ממשיך תור שהפעלה מחדש קטעה, הודעות העוזר שנושאות את השדות האלה נושאות גם את resume_reason.

timestamp הוא זמן ISO 8601 שבו יצירת תוכן ההודעה הסתיימה בתהליך שיצר אותה. הערך מגיע משעון המכונה הזו, אז השתמשו בו לתצוגה בלבד ואל תסדרו הודעות לפיו. תור API אחד יכול לייצר כמה הודעות עוזר שחולקות message.id, כל אחת עם timestamp משלה. כשהשדה נעדר, חזרו לזמן שבו קיבלתם את ההודעה.

context_usage הוא עותק מובנה של דוח /context, מטיפוס SDKContextUsage, והוא דורש Agent SDK מגרסה v0.3.232 ואילך. כששולחים /context כ-prompt, Claude Code מוסר את הדוח כהודעת עוזר ש-message.content שלה מחזיק את טבלת ה-markdown, ומצמיד את context_usage לאותה הודעה. Claude Code לא מגדיר את השדה על שום הודעת עוזר אחרת, וגרסאות קודמות מוסרות את טבלת /context בלעדיו, אז קראו את הפירוט מהשדה כשהוא קיים וחזרו לטקסט ה-markdown כשהוא לא.

usage_report הוא עותק מובנה של דוח /usage, מטיפוס SDKUsageReport, והוא דורש Agent SDK מגרסה v0.3.273 ואילך. כששולחים /usage כ-prompt, Claude Code מוסר את הדוח כהודעת עוזר ש-message.content שלה מחזיק את הטקסט. הוא מצמיד את usage_report לאותה הודעה רק כשהסשן עומד בכל התנאים האלה:

• הסשן מאומת עם פרטי גישה של claude.ai
• פרטי הגישה מציגים טיפוס תוכנית ידוע או נושאים את ה-scope user:profile
• החשבון לא בחיוב לפי שימוש

טוקן claude setup-token שמועבר כ-CLAUDE_CODE_OAUTH_TOKEN לא עומד בתנאי כברירת מחדל, כי הוא נושא רק את ה-scope user:inference. סשנים אחרים, כמו סשנים עם מפתח API, מוסרים את הטקסט בלי השדה, וכך גם גרסאות קודמות. קראו את הדוח מהשדה כשהוא קיים וחזרו לטקסט כשהוא לא.

#SDKUserMessage

הודעת קלט של המשתמש.

type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_id?: string;
  agent_id?: string;
  message: MessageParam; // From Anthropic SDK
  pasted_content?: MessageParam["content"][];
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  shouldQuery?: boolean;
  client_composed?: true;
  tool_use_result?: unknown;
  priority?: "now" | "next" | "later";
  origin?: SDKMessageOrigin;
  inline_pastes?: string[];
};

הגדר את pasted_content כדי לשלוח תוכן שהמשתמש הדביק בממשק ההנחיה שלך במקום להקליד, רשומה אחת לכל הדבקה, וכל רשומה היא מחרוזת או מערך של בלוקי תוכן. Claude Code מצרף את הטקסט של כל רשומה אחרי הטקסט שהוקלד, לפי הסדר, ועשוי לעטוף כל הדבקה בתגיות <pasted_content>. מתעלמים מבלוקים שאינם טקסט, לכן שלח תמונות ומסמכים ב-message.content. דורש Agent SDK v0.3.277 או חדש יותר.

הגדר את inline_pastes כדי לומר ל-Claude Code אילו חלקים של message.content המשתמש הדביק במקום להקליד, מחרוזת אחת לכל הדבקה. טקסט ההנחיה נשאר במקום שבו המשתמש שם אותו. Claude Code עשוי לעטוף כל הדבקה מהרשימה בתגיות <pasted_content> במקום שבו היא עומדת, כדי ש-Claude יוכל להבחין בין חומר שהודבק לבין המילים של המשתמש עצמו. נעטפות רק הדבקות בבלוק הטקסט האחרון של ההנחיה. דורש TypeScript Agent SDK v0.3.280 או חדש יותר.

לכל שדה הדבקה יש מגבלת גודל:

• pasted_content: אם הרשומות יחד עם בלוקי התוכן שבתוכן מונות יותר מ-1,000, Claude Code מתעלם מהשדה כולו.
• inline_pastes: Claude Code משתמש ב-100 הרשומות הראשונות שאינן ריקות ומתעלם מהשאר.

הגדר את shouldQuery, את client_composed או את priority כדי לשנות את האופן שבו Claude Code מטפל בהודעה שאתה שולח:

• shouldQuery: הגדר אותו ל-false כדי לצרף את ההודעה לתמליל בלי להפעיל תור של העוזר. ההודעה מוחזקת וממוזגת לתוך הודעת המשתמש הבאה שכן מפעילה תור. השתמש בזה כדי להזריק הקשר, כמו הפלט של פקודה שהרצת מחוץ לערוץ, בלי להוציא על זה קריאה למודל.
• client_composed: הגדר אותו ל-true כדי ש-Claude Code ימסור את טקסט ההודעה כפי שנכתב. אז Claude Code לא מרחיב אזכורים של @path או של @server:resource, ולא מריץ טקסט שמתחיל ב-/ כפקודה. כשהאפשרות verbatimPrompts פועלת, ה-SDK מגדיר את השדה בכל הודעה. דורש TypeScript Agent SDK v0.3.280 או חדש יותר ו-Claude Code v2.1.248 או חדש יותר.
• priority: שולט מתי הודעה שאתה שולח במהלך תור שרץ מגיעה אל Claude:
  • 'next', או כשאין שדה priority: Claude קורא את ההודעה באותו תור, מיד כשקריאות הכלים שהוא מריץ מסתיימות. אם התור מסתיים קודם, ההודעה מתחילה את התור הבא.
  • 'later': Claude Code מחזיק את ההודעה עד סיום התור ושולח אותה כתור חדש.
  • 'now' עם origin: { kind: "human" }: ב-Claude Code v2.1.286 או חדש יותר, עבודה שיכולה להמשיך ברקע עוברת לשם, ו-Claude קורא את ההודעה באותו תור. עבודה שיכולה לעבור כוללת פקודות מעטפת, תת-סוכנים וקריאות לכלי MCP. ב-v2.1.287 או חדש יותר זה כולל גם קריאות WebFetch ו-WebSearch. כש-Claude רק כותב תשובה, או כשהעבודה שהוא מריץ לא יכולה לעבור, Claude Code קוטע את התור במקום זאת ו-Claude קורא את ההודעה מיד אחר כך.
  • 'now' בלי אותו origin: Claude Code קוטע את התור ו-Claude קורא את ההודעה מיד אחר כך.

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

const message: SDKUserMessage = {
  type: "user",
  message: { role: "user", content: "Skip the integration tests and summarize what you have so far" },
  parent_tool_use_id: null,
  priority: "now",
  origin: { kind: "human" },
};

הודעת משתמש שתת-סוכן מייצר, כמו ה-tool_result של אחת מקריאות הכלים שלו עצמו, נושאת agent_id. ראה SDKAssistantMessage, שמגדיר את השדה ואת דרישת הגרסה שלו.

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

• כלי ה-Agent: tool_use_result הוא AgentOutput. הצג ממנו במקום לנתח את טקסט ה-tool_result. ה-content של תוצאת completed מחזיק את הדוח של תת-הסוכן, או, אצל תת-סוכן שהדוח שלו עובר דרך קריאת כלי SubagentHandback, הערה קצרה על ההחזרה הזו במקום הדוח. במצב אוטומטי ב-Claude Code v2.1.271 או חדש יותר, כל תת-סוכן שמייצר תוצאת completed מדווח כך אלא אם הוא פיצול, ו-Claude מקבל את הדוח כהודעה נפרדת מתת-הסוכן.
• קריאת WebFetch או WebSearch ש-Claude Code העביר לרקע כדי למסור הודעת 'now': להודעת המשתמש שנושאת את ה-tool_result של הקריאה הזו יש tool_use_result שמוגדר ל-{ detachedToolCall: true }. הקריאה עדיין רצה, ו-Claude מקבל את התוצאה שלה כשהיא מסתיימת. לא מגיע אחרי זה tool_result שני לאותו tool_use_id, לכן אם היישום שלך מצייר שורה לכל קריאת כלי, סמן את השורה הזו כמועברת לרקע כשההודעה הזו מגיעה. דורש Claude Code v2.1.287 או חדש יותר.
• כלי MCP שהתוצאה שלו מכילה בלוקי resource_link: tool_use_result הוא אובייקט עם מערך resourceLinks של רשומות SDKMcpResourceLink. Claude מקבל כל קישור כשורת טקסט בבלוק tool_result, לכן קרא את resourceLinks כדי להציג את הקבצים שהשרת החזיר במקום לנתח את הטקסט הזה. Claude Code משמיט את resourceLinks כשאין קישורים בתוצאה וגם בתוצאות מתת-סוכנים, שומר לכל היותר 50 קישורים לתוצאה, ומפסיק להוסיף קישורים ברגע שהמערך מגיע ל-64 KiB של JSON ממוסר. resourceLinks דורש Agent SDK v0.3.257 או חדש יותר.
• כלי MCP שמחזיר structuredContent: tool_use_result הוא אובייקט שהאיבר structuredContent שלו מחזיק את מה שהשרת שלח, והאיבר content שלו מחזיק את הערך McpOutput. תוצאות מתת-סוכנים לא נושאות structuredContent.
• כלי MCP שה-structuredContent שלו עובר סריאליזציה ליותר מ-1,048,576 תווים של JSON: Claude Code משמיט את structuredContent מ-tool_use_result ומגדיר במקומו structuredContentOmitted: true, כדי שהיישום שלך יוכל להבחין בין אובייקט שהושמט לבין כלי שלא שלח אובייקט. האיברים האחרים, כמו content ו-resourceLinks, נשארים, ומה ש-Claude מקבל לא משתנה. Claude Code v2.1.287 או חדש יותר מחיל את התקרה הזו. שני סוגים של כלים נבדלים:
  • כלים משרתי SDK בתוך התהליך פטורים ומוסרים את האובייקט בשלמות.
  • לכלי שרשומת tools/list שלו מצהירה על משאב ui:// של MCP Apps יש מגבלה של 8,388,608 תווים ב-Claude Code v2.1.295 או חדש יותר, וגרסאות שלפני v2.1.295 פוטרות אותו.

#SDKUserMessageReplay

הודעת משתמש שהושמעה מחדש, עם UUID חובה.

type SDKUserMessageReplay = {
  type: "user";
  uuid: UUID;
  session_id: string;
  message: MessageParam;
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  client_composed?: true;
  tool_use_result?: unknown;
  origin?: SDKMessageOrigin;
  isReplay: true;
};

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

#SDKResultMessage

הודעת תוצאה סופית.

type SDKResultMessage =
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      api_error_status?: number | null;
      num_turns: number;
      result: string;
      stop_reason: string | null;
      ttft_ms?: number;
      ttft_stream_ms?: number;
      time_to_request_ms?: number;
      user_message_uuid?: string;
      user_message_uuids?: string[];
      resume_reason?: string;
      local_command?: string;
      request_sent_wall_ms?: number;
      first_content_frame_ms?: number;
      first_stream_post_ms?: number;
      first_stream_post_ack_ms?: number;
      first_stream_post_queue_wait_ms?: number;
      first_stream_post_queued_behind?: "durable_post" | "ephemeral_post" | "retry_backoff" | "hold" | "none";
      first_stream_post_wall_ms?: number;
      first_text_post_ms?: number;
      first_text_post_queue_wait_ms?: number;
      first_text_post_queued_behind?: "durable_post" | "ephemeral_post" | "retry_backoff" | "hold" | "none";
      first_text_post_wall_ms?: number;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      queued_turn_count?: number;
      structured_output?: unknown;
      deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };
      terminal_reason?: TerminalReason;
      result_index?: number;
      fast_mode_state?: FastModeState;
      fast_mode_disabled_reason?: FastModeDisabledReason;
      origin?: SDKMessageOrigin;
    }
  | {
      type: "result";
      subtype:
        | "error_max_turns"
        | "error_during_execution"
        | "error_max_budget_usd"
        | "error_max_structured_output_retries";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      stop_reason: string | null;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      queued_turn_count?: number;
      errors: string[];
      startup_failure_reason?: SDKStartupFailureReason;
      user_message_uuid?: string;
      user_message_uuids?: string[];
      resume_reason?: string;
      terminal_reason?: TerminalReason;
      result_index?: number;
      fast_mode_state?: FastModeState;
      fast_mode_disabled_reason?: FastModeDisabledReason;
      origin?: SDKMessageOrigin;
    };

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

• api_error_status: קוד הסטטוס HTTP של שגיאת ה-API שסיימה את השיחה. חסר או null כשהתור הסתיים בלי שגיאת API.
• ttft_ms: זמן עד האסימון הראשון באלפיות השנייה, שנמדד כשמגיעה הודעת העוזר השלמה הראשונה. קיים רק בזרוע ההצלחה.
• ttft_stream_ms: זמן באלפיות השנייה עד אירוע הזרם message_start הראשון, כשזרם התשובה נפתח. נמוך מ-ttft_ms. הפער בין השניים הוא הזמן שהושקע בהזרמת ההודעה הראשונה. קיים רק בזרוע ההצלחה.
• time_to_request_ms: זמן באלפיות השנייה מתחילת התור עד ש-Claude Code שולח את בקשת ה-API. קיים רק בזרוע ההצלחה. דורש Claude Code v2.1.162 או מאוחר יותר.
• user_message_uuid: ה-uuid של ההודעה ששלחת ושתור זה ענה עליה. ראה user_message_uuid לגבי אילו תוצאות נושאות אותו.
• user_message_uuids: ערכי ה-uuid של כל הודעה ששלחת וש-Claude Code ענה עליה בתור זה. ראה user_message_uuids.
• resume_reason: למה תור זה ממשיך תור שהפעלה מחדש קטעה. קיים בשתי הזרועות. ראה resume_reason.
• local_command: שם הפקודה שהתור שיגר, בתוצאת ההצלחה של תור שבו פקודה הושלמה בלי כניסה ללולאת הסוכן, למשל /compact. השם מקופל לאותיות קטנות ולקווים תחתונים, ולכן /reload-plugins מדווח reload_plugins. פקודה ששרת MCP מספק, וגם /mcp המובנה, מדווחות mcp. פקודה שהגדרת בעצמך מדווחת custom. הארגומנטים לעולם אינם כלולים. חסר בכל תור שנכנס ללולאת הסוכן, ובשליחות שלא הריצו פקודה. דורש Agent SDK v0.3.268 או מאוחר יותר.
• request_sent_wall_ms: אלפיות שנייה מאז epoch שבהן Claude Code שיגר את בקשת ה-API, לצורך חיבור מול חותמות זמן בצד השרת. קיים רק יחד עם user_message_uuid, בתוצאת הצלחה שבה is_error הוא false ושתורה שלח בקשת API.
• first_content_frame_ms: זמן באלפיות השנייה עד אירוע הזרם content_block_start או content_block_delta הראשון, כשבלוקי חשיבה נספרים כתוכן. קיים רק בזרוע ההצלחה, כש-is_error הוא false. דורש Agent SDK v0.3.260 או מאוחר יותר.
• first_stream_post_ms, first_stream_post_ack_ms, first_stream_post_wall_ms: תזמונים להעלאת אירוע הזרם הראשון של התור. Claude Code רושם אותם רק בסשנים שהוא מזרים אל claude.ai, למשל סשנים בענן, והתוצאות ש-query() מניב אינן נושאות אותם. דורש Agent SDK v0.3.260 או מאוחר יותר.
• usage: לולאת הסוכן הראשית בלבד. לא כולל קריאות של תת-סוכן ושל מודל עזר, והוא לכל תור בסשנים של קלט בזרימה. העדף את modelUsage לחשבונאות של אסימונים ועלות.
• modelUsage: סכומים לפי מודל לכל קריאת מודל שנעשתה דרך צינור ה-query במהלך קריאת query() זו, כולל הלולאה הראשית, תת-סוכנים, וקריאות פנימיות כגון דחיסה וסוכני Workflow. קריאות עזר מחוץ לצינור הזה, כגון מסווג ההרשאות ובקשות ספירת אסימונים, אינן כלולות. קריאה שמחדשת סשן סופרת גם את הסכומים לפי מודל ששוחזרו מקריאות קודמות של הסשן. בסשנים של קלט בזרימה הסכומים מצטברים לאורך התורים, ולכן יש לקרוא את התוצאה האחרונה במקום לסכם את כל התוצאות. ראה מעקב עלויות במצב קלט בזרימה לאיפוסים, ושחזור סכומים אחרי קריסת סשן לתוצאות מאופסות.
• total_cost_usd: עלות משוערת מצטברת ב-USD, שמכסה את אותן הקריאות כמו modelUsage ומאופסת באותן נקודות. קריאה שמחדשת סשן סופרת גם את הסכומים ששוחזרו מקריאות קודמות של הסשן. זו הערכה, לא דוח חיוב. ראה מעקב עלות ושימוש להסתייגויות לגבי דיוק.
• queued_turn_count: מספר ההודעות ששלחת עם origin: { kind: "human" } שעדיין ממתינות ברגע ש-Claude Code ייצר את התוצאה. ראה queued_turn_count לגבי מה ש-0 ושדה חסר אומרים לך.
• result_index: המקום של תוצאה זו בסדר המסירה של הריצה, בספירה מ-0 על פני כל תוצאה שהתהליך כותב. קיים בשתי הזרועות. תוצאה שכתיבתה נכשלת עדיין צורכת את המספר שלה, ולכן פער ברצף אומר שתוצאה אבדה. דורש Agent SDK v0.3.268 או מאוחר יותר.
• startup_failure_reason: למה Claude Code סירב להתחיל, בתוצאת error_during_execution שהוא כותב לפני שהוא יוצא בכשל הפעלה ידוע. ראה startup_failure_reason לערכים ולאילו כשלים נושאים אותו. דורש Agent SDK v0.3.274 או מאוחר יותר.
• terminal_reason: למה הלולאה הסתיימה. אחד מהערכים "completed", "max_turns", "tool_deferred", "aborted_streaming", "aborted_tools", "hook_stopped", "stop_hook_prevented", "background_requested", "blocking_limit", "rapid_refill_breaker", "prompt_too_long", "image_error", "model_error", "api_error", "malformed_tool_use_exhausted", "budget_exhausted", "structured_output_retry_exhausted", "tool_deferred_unavailable", או "turn_setup_failed".
• fast_mode_state: אחד מהערכים "on", "off", או "cooldown".
• fast_mode_disabled_reason: למה מצב מהיר אינו זמין כרגע. חסר כשדבר אינו חוסם את מצב מהיר, אם כי בקשה עדיין עשויה לרוץ במהירות רגילה. במהלך הצינון שאחרי מגבלת קצב של מצב מהיר, Claude Code מדווח fast_mode_state: "cooldown" בלי קוד סיבה, ומפעיל מחדש את מצב מהיר כשהצינון פג. דורש Claude Code v2.1.219 או מאוחר יותר.

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

אותו זוג שדות מופיע ב-SDKSystemMessage וב-SDKControlInitializeResponse, כך שתוכל לקרוא את המצב של מצב מהיר לפני התור הראשון.

שדה origin מעביר את SDKMessageOrigin של הודעת המשתמש שהפעילה תוצאה זו. תוצאות שנושאות origin: { kind: "task-notification" } כוללות:

• תורי המשך סינתטיים: כשה-SDK מזריק תור המשך סינתטי, למשל למשימת רקע שהסתיימה, ה-SDKResultMessage המתקבל נושא סוג זה
• משימות מתוזמנות שהופעלו והודעות מסשנים אחרים: משימות מתוזמנות בענן שהטריגר שלהן הופעל, והודעות שאומתו בשרת מהסשנים האחרים שלך, מגיעות גם הן עם סוג זה, וכל אחת עם ה-subkind המתואר בתת-סוגים של התראת משימה

בדוק את kind כדי להבדיל תוצאות שעונות על הפרומפט שלך מהמשכי הזרקה, לפני ניתוב או דיכוי. אם היישום שלך מצהיר על ריצות מתוזמנות, גם התוצאות שלהן נושאות kind: "task-notification", ולכן אין לדכא לפי kind לבדו.

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

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

כש-hook מסוג PreToolUse מחזיר permissionDecision: "defer", לתוצאה יש stop_reason: "tool_deferred", ו-deferred_tool_use נושא את id, name ו-input של הכלי הממתין. קרא שדה זה כדי להציג את הבקשה בממשק שלך, ואז חדש עם אותו session_id כדי להמשיך. ראה דחיית קריאת כלי למועד מאוחר יותר למחזור השלם.

#user_message_uuid

ה-uuid של ה-SDKUserMessage שהתור עונה עליו, מהדהד כדי שתוכל להתאים את תשובת Claude Code להודעה ששלחת. Claude Code מהדהד uuid רק אם הגדרת אחד על ההודעה. השדה אופציונלי ב-SDKUserMessage, ופרומפט מסוג מחרוזת שמועבר ל-query() אינו נושא uuid.

על איזו מההודעות שלך תור עונה תלוי באופן שבו התור התחיל:

• הודעה רגילה ששלחת, כלומר הודעה בלי isSynthetic: true: התור עונה על ההודעה הזו לכל הריצה שלו. כששולחים כמה הודעות בסמיכות, Claude Code יכול למזג אותן לתור אחד, ואז השדה נושא רק את ה-uuid של ההודעה האחרונה. כדי להתאים את התשובה לכל אחת מההודעות שמוזגו, השתמש ב-user_message_uuids.
• הודעה ששלחת עם isSynthetic: true: התור עונה על ההודעה הזו בהתחלה. אם Claude Code קולט הודעה רגילה שלך בין קריאות כלים, התור עונה על ההודעה שנקלטה מאותו רגע. הד של uuid של הודעה סינתטית דורש Agent SDK v0.3.265 או מאוחר יותר. גרסאות מוקדמות יותר לא מהדהדות דבר בתורים סינתטיים.
• הפרומפט ש-Claude Code מייצר כדי להמשיך תור שנקטע תחת CLAUDE_CODE_RESUME_INTERRUPTED_TURN: כשהפרומפט האחרון של התור שנקטע הוא הודעה רגילה ששלחת, בין אם היא פתחה את התור ובין אם Claude Code קלט אותה במהלך התור, התור המומשך עונה על ההודעה הזו בהתחלה. resume_reason מבדיל את המסגרות של התור המומשך מאלה של הניסיון שנקטע. כשהפרומפט האחרון אינו הודעה רגילה שלך, התור המומשך אינו עונה על שום הודעה שלך בהתחלה. אם Claude Code קולט הודעה רגילה שלך בין קריאות כלים, התור עונה על ההודעה שנקלטה מאותו רגע. הד של הפרומפט של התור שנקטע דורש Agent SDK v0.3.268 או מאוחר יותר.
• כל פרומפט אחר ש-Claude Code יצר בעצמו: התור אינו עונה על שום הודעה שלך בהתחלה, והמסגרות שלו אינן נושאות הד. אם Claude Code קולט הודעה רגילה שלך בין קריאות כלים, התור עונה על ההודעה הזו מאותו רגע. הד הקליטה דורש Agent SDK v0.3.265 או מאוחר יותר. גרסאות מוקדמות יותר לא מהדהדות דבר בתורים אלה.

Claude Code מהדהד את ה-uuid של ההודעה שנענתה בשלושה סוגי מסגרות:

• התוצאה: כל תוצאה של תור שענה על הודעה ששלחת. כל תוצאה כזו נושאת אותו ב-Agent SDK v0.3.265 או מאוחר יותר. לפני v0.3.265, לתוצאת ההצלחה של תור שהתחיל בהודעה רגילה חסר השדה כשהתור לא שלח בקשת API או הסתיים בקריאת כלי שנדחתה. לפני v0.3.246 גם לתוצאות שגיאה חסר השדה, ולפני v0.3.216 הוא חסר בכל תוצאה.
• התשובה הראשונה של התור: הודעת העוזר הראשונה, ועם includePartialMessages גם אירוע הזרם הראשון ש-event.type שלו אינו ping, כדי שתוכל לקשור את התשובה לפני שהתוצאה מגיעה. הד של התשובה הראשונה דורש Agent SDK v0.3.246 או מאוחר יותר. לפני v0.3.269, עם includePartialMessages, Claude Code הגדיר אותו רק על אירוע הזרם הראשון הזה, או על הודעת העוזר הראשונה כשהתור לא הזרים דבר. כשההודעה שהתור עונה עליה משתנה באמצע התור, גם התשובה הראשונה שאחרי השינוי נושאת את השדה, ב-Agent SDK v0.3.265 או מאוחר יותר. גרסאות מוקדמות יותר מגדירות אותו על מסגרת תשובה אחת לכל תור.
• כל מסגרת thinking_tokens של התור: כדי שתוכל לייחס את התקדמות החשיבה להודעה ששלחת, בלי להמתין לתשובה הראשונה של התור. דורש Agent SDK v0.3.260 או מאוחר יותר.

Claude Code משמיט את השדה במקרים אלה:

• מסגרות תשובה שאינן התשובות הראשונות האלה
• מסגרות של תת-סוכן
• תורים שאינם עונים על הודעה שלך, או שעונים על הודעה ששלחת בלי uuid
• תוצאות שאינן עונות על הודעה ששלחת, למשל התוצאה המאופסת אחרי שתהליך worker קרס

כש-hook מסוג UserPromptSubmit חוסם הודעה שמתחילה תור משלה, או עוצר אותה עם continue: false, עדיין מתקבלת תוצאה להודעה זו. זו תוצאת הצלחה עם is_error: false ועם num_turns: 0, ה-result שלה הוא הודעת החסימה או הודעת העצירה, והיא מהדהדת את ה-uuid של ההודעה לפי אותם כללים כמו כל תוצאה אחרת. לתוצאה אין terminal_reason, ושום דבר עליה מלבד טקסט ה-result אומר ש-hook סיים את התור. הודעה ש-hook חוסם בזמן שתור אחר רץ עשויה לא לקבל תוצאה: ראה user_message_uuids.

#user_message_uuids

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

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

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

זה תקף כשפלט ה-hook הוא חסימה בלבד. אם הפלט מגדיר continue: false, גם לצד decision: "block", או שה-hook הוא prompt hook שעונה ok: false בלי continueOnBlock: true, Claude Code עוצר את ההודעה במקום להשמיט אותה. ההודעה ממתינה לתור משלה, מקבלים תוצאה עבורה, והטקסט שלה נשאר בשיחה, כך ש-Claude רואה אותה בתור הבא.

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

#resume_reason

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

Claude Code מגדיר את השדה על שני סוגים של מסגרות:

• התוצאה של התור שנמשך: גם בזרוע ההצלחה וגם בזרוע השגיאה, בין אם התוצאה נושאת user_message_uuid ובין אם לא.
• מסגרות התשובה של התור שנמשך: אלה שנושאות user_message_uuid.

הערך הוא אסימון קצר באותיות קטנות, כגון interrupted_turn.

#queued_turn_count

מספר ההודעות ששלחת עם origin: { kind: "human" } שעדיין ממתינות בתור הפקודות כש-Claude Code הפיק את התוצאה. דורש Agent SDK v0.3.242 או מאוחר יותר.

מה 0 ושדה חסר אומרים לך:

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

#startup_failure_reason

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

הגדר את CLAUDE_CODE_STARTUP_FAILURE_RESULTS ל-1 ב-env כדי לקבל את התוצאה הזו לכל ערך SDKStartupFailureReason. בלי המשתנה הזה, Claude Code כותב את התוצאה רק עבור הכשלים האלה, והשאר מסתיימים בפלט stderr, יציאה עם קוד שאינו אפס, ובלי הודעת תוצאה:

• חידוש ש-Claude Code עוצר כי הוא לא יכול להחזיר את הסשן ל-worktree שלו, עם worktree_unverified או worktree_resume_refused. הסעיף ההוא אומר איזו שגיאה נושאת איזה ערך.
• continue שנדחה של שיחה שסשן רקע מחזיק, עם session_held_by_background. עבור resume שנדחה של שיחה כזו, Claude Code כותב את התוצאה רק כשהמשתנה מוגדר.
• התחלה ש-Claude Code מסרב לה כי failIfUnavailable פועל וה-sandbox לא יכול להתחיל, עם sandbox_required_unavailable.
• התחלה ש-Claude Code מסרב לה כי ~/.claude.json אינו JSON תקין, עם config_file_invalid.

הטיפוס SDKStartupFailureReason מפרט את הערכים ש-startup_failure_reason יכול להחזיק:

type SDKStartupFailureReason =
  | "org_pin_api_key_conflict"
  | "provider_not_allowed"
  | "org_verify_failed"
  | "org_pin_mismatch"
  | "managed_settings_invalid"
  | "remote_settings_required_unavailable"
  | "gateway_signin_required"
  | "gateway_access_denied"
  | "proxy_invalid"
  | "temp_dir_unusable"
  | "cwd_unavailable"
  | "shell_tool_missing"
  | "session_held_by_background"
  | "worktree_resume_refused"
  | "worktree_unverified"
  | "cli_version_too_old"
  | "bypass_root"
  | "org_config_required_unavailable"
  | "org_config_refused"
  | "sandbox_required_unavailable"
  | "config_file_invalid";

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

#SDKSystemMessage

הודעת אתחול מערכת.

type SDKSystemMessage = {
  type: "system";
  subtype: "init";
  uuid: UUID;
  session_id: string;
  agents?: string[];
  apiKeySource: ApiKeySource;
  betas?: string[];
  claude_code_version: string;
  cwd: string;
  tools: string[];
  mcp_servers: {
    name: string;
    status: string;
    source?: string;
  }[];
  model: string;
  permissionMode: PermissionMode;
  slash_commands: string[];
  terminal_slash_commands?: string[];
  output_style: string;
  skills: string[];
  plugins: { name: string; path: string }[];
  plugin_errors?: {
    plugin: string;
    type: string;
    message: string;
    path?: string;
  }[];
  fast_mode_state?: FastModeState;
  fast_mode_disabled_reason?: FastModeDisabledReason;
  effort?: "low" | "medium" | "high" | "xhigh" | "max" | null;
  capabilities?: string[];
};

fast_mode_state מדווח על מצב המצב המהיר של הסשן. כשמשהו חוסם את המצב המהיר, fast_mode_disabled_reason מציין את הבדיקה שחסמה אותו. השדה דורש Claude Code v2.1.219 או מאוחר יותר. לקודי הסיבה ולמשמעויות שלהם, ראה fast_mode_disabled_reason בהודעת התוצאה.

terminal_slash_commands מציין את הרשומות ב-slash_commands שהממשק שלהן קשור לטרמינל המקומי, כגון exit. אפשר לשלוח אותן כמו כל רשומה אחרת ב-slash_commands. השדה קיים כדי שלקוח מרוחק או נייד יוכל להסתיר אותן מתפריטי הפקודות שלו. השדה נוכח רק כשהוא לא ריק, ודורש Agent SDK v0.3.229 או מאוחר יותר.

• source בכל רשומת mcp_servers: מאיפה הגיעה הגדרת השרת, עם אותם ערכים כמו source של McpServerStatus. דורש Agent SDK v0.3.274 או מאוחר יותר.
• effort: רמת המאמץ שהוגדרה לתור הבא של הסשן, או null כש-Claude Code לא שולח רמה. Claude Code מגדיר את השדה רק בהודעת ה-init שהוא שולח ללקוחות Remote Control, ומשמיט אותו מהודעת ה-init שהיישום שלך קורא. דורש Agent SDK v0.3.234 או מאוחר יותר.

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

מערך plugin_errors מפרט כשלי טעינה של תוספים. רשומה מתארת או תוסף שלא נטען וחסר מ-plugins, או תוסף שנטען בלי אחד מחלקיו, כגון קובץ ה-hooks שלו. המפתח מושמט כששום דבר לא נכשל. SDKSystemMessage מצהיר על plugin_errors ב-Agent SDK v0.3.283 או מאוחר יותר.

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

הטבלה למטה מפרטת את השדות של כל רשומת plugin_errors.

#SDKPartialAssistantMessage

הודעה חלקית בזרימה (רק כש-includePartialMessages הוא true).

השדה parent_tool_use_id תמיד null: אירועי זרם נפלטים רק עבור הסשן הראשי. לייחוס של subagent, השתמש בהודעות שלמות, שנושאות agent_id ו-parent_tool_use_id, או הפעל את forwardSubagentText כדי לקבל טקסט וחשיבה של subagent כהודעות שלמות.

type SDKPartialAssistantMessage = {
  type: "stream_event";
  event: BetaRawMessageStreamEvent; // From Anthropic SDK
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
  ttft_ms?: number; // Time to first token in ms, present only on message_start events
  user_message_uuid?: string;
  user_message_uuids?: string[];
  resume_reason?: string;
};

Claude Code מגדיר את user_message_uuid ואת user_message_uuids על אירוע הזרם הראשון שאינו ping של התור, ושוב כשההודעה שהתור עונה עליה משתנה, בתנאים שב-user_message_uuid. כשהתור ממשיך תור שהפעלה מחדש קטעה, אירועי הזרם שנושאים את השדות האלה נושאים גם resume_reason.

#SDKCompactBoundaryMessage

הודעה שמציינת גבול דחיסה של שיחה.

type SDKCompactBoundaryMessage = {
  type: "system";
  subtype: "compact_boundary";
  uuid: UUID;
  session_id: string;
  compact_metadata: {
    trigger: "manual" | "auto";
    pre_tokens: number;
  };
};

#SDKInformationalMessage

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

ב-Claude Code v2.1.227 או מאוחר יותר, systemMessage של hook יכול להגיע כהודעה הזו, כשכל שורה מקבלת קידומת של שם ה-hook, כגון PostToolUse:Bash says:. כל סעיף אירוע בדף ה-hooks אומר איך הפלט מוצג.

הצג את content כטקסט רגיל ברמת ה-level הנתונה.

type SDKInformationalMessage = {
  type: "system";
  subtype: "informational";
  content: string;
  level: "info" | "notice" | "suggestion" | "warning";
  tool_use_id?: string;
  prevent_continuation?: boolean;
  tag?: string;
  uuid: UUID;
  session_id: string;
};

#SDKWorkerShuttingDownMessage

נפלט בפירוק מסודר של worker כדי שלקוחות מרוחקים יוכלו להציג למה ה-worker יצא במקום להמתין ל-timeout של heartbeat. ה-reason הוא מחרוזת snake_case קצרה שה-CLI המארח מגדיר, כגון "host_exit" או "remote_control_disabled". פעל לפי זה רק בזמן זרימה חיה. סשן שחודש משחזר מופעים קודמים של ההודעה הזו, ולכן התעלם מהם במקרה הזה.

type SDKWorkerShuttingDownMessage = {
  type: "system";
  subtype: "worker_shutting_down";
  reason: string;
  uuid: UUID;
  session_id: string;
};

#SDKPluginInstallMessage

אירוע התקדמות של התקנת תוסף. נשלח כאשר CLAUDE_CODE_SYNC_PLUGIN_INSTALL מוגדר, כדי שאפליקציית Agent SDK שלך תוכל לעקוב אחרי התקנת תוספי marketplace לפני התור הראשון. הסטטוסים started ו-completed תוחמים את ההתקנה הכוללת. הסטטוסים installed ו-failed מדווחים על marketplaces בודדים וכוללים את name.

type SDKPluginInstallMessage = {
  type: "system";
  subtype: "plugin_install";
  status: "started" | "installed" | "failed" | "completed";
  name?: string;
  error?: string;
  uuid: UUID;
  session_id: string;
};

#SDKPermissionDeniedMessage

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

• עם callback של canUseTool וברירת המחדל permissionPrompts: 'host': בקשות הרשאה עוברות ל-callback שלך, והאירוע הזה מדווח על הדחיות ש-Claude Code מחליט עליהן בעצמו בלי לקרוא לו.
• בלי אף אחד מהם: ריצת -p בלבד, או query() שלא מגדיר לא את canUseTool ולא את permissionPromptToolName, דוחה כל קריאת כלי שהייתה מעלה בקשה אלא אם hook של PermissionRequest מתיר אותה, והאירוע הזה מדווח על הדחיות האלה וגם על אלה ש-Claude Code מחליט עליהן בעצמו. לפני v2.1.223, Claude Code לא שלח את האירוע הזה בריצות בלי callback.
• עם כלי בקשת MCP, שמוגדר באמצעות permissionPromptToolName או הדגל --permission-prompt-tool, וברירת המחדל permissionPrompts: 'host': Claude Code לא שולח את האירוע הזה בכלל, גם לא עבור דחיות הכללים שהוא מחליט עליהן בעצמו.
• עם permissionPrompts: 'none': Claude Code דוחה את הקריאות שהיו מעלות בקשה, גם כאשר canUseTool או כלי בקשת MCP מוגדרים בנוסף, והאירוע הזה מדווח על הדחיות האלה וגם על אלה ש-Claude Code מחליט עליהן בעצמו. דורש Claude Code v2.1.259 או חדש יותר.

בכל הגדרה, האירוע הזה מדלג על כל דחייה שהוחלטה במסלול ה-hook של PreToolUse, בין אם ה-hook דחה את הקריאה בעצמו ובין אם כלל deny דרס החלטת allow או ask של ה-hook. האירוע הוא גם best-effort: מדי פעם Claude Code רושם דחייה בלי לשלוח את האירוע הזה, ולכן permission_denials בהודעת התוצאה הוא הרשומה הסמכותית.

type SDKPermissionDeniedMessage = {
  type: "system";
  subtype: "permission_denied";
  tool_name: string;
  tool_use_id: string;
  agent_id?: string;
  decision_reason_type?: string;
  decision_reason?: string;
  message: string;
  uuid: UUID;
  session_id: string;
};

#SDKPermissionDenial

מידע על שימוש בכלי שנדחה.

type SDKPermissionDenial = {
  tool_name: string;
  tool_use_id: string;
  tool_input: Record<string, unknown>;
};

#SDKContextUsage

צורה מובנית של דוח /context, שנישאת כ-context_usage על SDKAssistantMessage שמספק תוצאת /context. Agent SDK מגרסה v0.3.232 ואילך מייצא את הטיפוס. בניגוד ל-SDKControlGetContextUsageResponse, הוא נושא רק את הנתונים הדרושים להצגת פירוט השימוש, בלי שדות תצוגה כגון color ו-gridRows. Claude Code מחשב את הדוח באמצעות בקשות API לספירת טוקנים שלא מופיעות בזרם ההודעות. ראה איך הבקשות האלה מטופלות.

type SDKContextUsage = {
  model: string;
  total_tokens: number;
  raw_max_tokens: number;
  percentage: number;
  over_limit?: {
    tokens_over: number;
    kind: "hard_limit" | "compaction_window";
  };
  categories: SDKContextUsageCategory[];
  mcp_tools: {
    name: string;
    server_name: string;
    tokens: number;
  }[];
  memory_files: {
    path: string;
    type: string;
    tokens: number;
  }[];
  agents: {
    agent_type: string;
    source: string;
    tokens: number;
  }[];
  skills?: {
    name: string;
    source: string;
    plugin_name?: string;
    tokens: number;
  }[];
};

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

over_limit.kind רושם איך Claude Code קבע את החלון, לא אם ה-API מקבל את הבקשה הבאה:

• hard_limit: החלון הוא מה ש-Claude Code מאמין שהוא המגבלה של המודל עצמו, שמעבר לה ה-API מסרב לבקשות
• compaction_window: החלון הוא חלון של מדיניות דחיסה, שעשוי לחפוף למגבלת המודל או לא

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

#SDKContextUsageCategory

שורה אחת בפירוט השימוש לפי קטגוריה של /context.

type SDKContextUsageCategory = {
  name: string;
  tokens: number;
  kind: "used" | "free" | "buffer" | "deferred";
};

הטבלה מפרטת מה Claude Code שם בכל שדה של שורה.

כל ערך kind אומר מה הטוקנים של השורה:

• used: תוכן שתופס את חלון ההקשר
• free: החלון שנותר
• buffer: עתודת הדחיסה
• deferred: סכמות כלים ש-Claude Code מחזיק מחוץ לחלון ומוציא מחישוב השימוש, מוצגות לצורך מודעות

#SDKUsageReport

צורה מובנית של דוח /usage, שנישאת כ-usage_report על SDKAssistantMessage שמספק תוצאת /usage. Agent SDK מגרסה v0.3.273 ואילך מייצא את הטיפוס. הטיפוס ניסיוני: צורתו עשויה להשתנות.

type SDKUsageReport = {
  session: {
    total_cost_usd: number;
    total_api_duration_ms: number;
    total_duration_ms: number;
    total_lines_added: number;
    total_lines_removed: number;
    model_usage: { [modelName: string]: ModelUsage };
  };
  rate_limits: {
    limits:
      | {
          kind: string;
          group: string;
          percent: number;
          resets_at: string | null;
          scope?: {
            model?: { display_name: string } | null;
            surface?: { display_name: string } | null;
          } | null;
          severity: string;
          is_active: boolean;
        }[]
      | null;
    extra_usage?: {
      is_enabled: boolean;
      monthly_limit: number | null;
      used_credits: number | null;
      utilization: number | null;
      currency?: string | null;
    } | null;
  } | null;
};

השדות ברמה העליונה הם session ו-rate_limits:

• session: הסכומים השוטפים של עלות ושימוש של Claude Code, שנקראים מאותו פנקס כמו total_cost_usd ו-modelUsage ב-SDKResultMessage. כל רשומת model_usage היא ModelUsage.
• rate_limits: שורות השימוש של התוכנית ב-limits וההוצאה על קרדיטי שימוש ב-extra_usage. הוא null כאשר Claude Code לא הצליח לקבל את השימוש של התוכנית, למשל כאשר לטוקן ה-OAuth של הסשן חסר ה-scope user:profile.

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

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

• מערך ריק אומר שהשרת דיווח שאין מונים.
• null אומר של-Claude Code אין שורות לדווח.

כל שורה של limits מתארת מונה שימוש אחד:

לפני Agent SDK v0.3.277, הטיפוס הכריז על severity ו-is_active כאופציונליים וברי-null, ושורה יכלה להגיע בלעדיהם.

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

• monthly_limit הוא null כאשר לחשבון הזה אין תקרת הוצאה משלו. בתוכניות Team ו-Enterprise, אל תציג null כלא מוגבל.
• is_enabled הוא false כל עוד קרדיטי שימוש לא יכולים לשלם עבור בקשות.

#SDKMessageOrigin

מקור של הודעה בתפקיד משתמש. זה מופיע כ-origin על SDKUserMessage ומועבר הלאה אל SDKResultMessage המתאים כדי שתוכל לדעת מה הפעיל תור נתון.

type SDKMessageOrigin =
  | { kind: "human" }
  | { kind: "channel"; server: string }
  | {
      kind: "peer";
      from: string;
      fromMode?: "bypass" | "prompting";
      name?: string;
      fromSession?: string;
      senderTaskId?: string;
      body?: string;
      verifiedPeerPid?: number;
    }
  | {
      kind: "task-notification";
      subkind?: "scheduled-trigger" | "peer-send-message";
      fireReason?: string;
      runId?: string;
    }
  | { kind: "coordinator" }
  | { kind: "auto-continuation" }
  | { kind: "unclassified" };

#תת סוגים של התראת משימה

כש Claude Code מעביר התראת משימה לתוך סשן, הוא מגדיר את subkind על origin של ההתראה אם שרתי Anthropic אימתו מאיפה ההתראה הגיעה. הוא גם מגדיר את subkind כשהאפליקציה שלך מצהירה על ההודעה כהרצה מתוזמנת בעצמה, מה שדורש TypeScript Agent SDK מגרסה v0.3.280 ואילך. subkind דורש Claude Code מגרסה v2.1.213 ואילך, והוא מקבל אחד משני ערכים:

• scheduled-trigger: ההתראה היא הפרומפט השמור של משימה מתוזמנת בענן, שנמסר כי אחד מהטריגרים של המשימה הופעל: לוח הזמנים שלה, טריגר ה API שלה, טריגר ה GitHub שלה, או Run now. גם פרומפט שהאפליקציה שלך מצהירה עליו כהרצה מתוזמנת נושא את הערך הזה. Claude Code מציג אותם למודל כמשימה שהוקצתה לסשן, עם הודעה שונה מההודעה שהתראות משימה אחרות נושאות.
• peer-send-message: ההתראה היא הודעה שאחד הסשנים האחרים שלך שלח עם כלי send_message בצד השרת, שסשנים בענן משתמשים בו כדי לשלוח הודעות זה לזה, לא כלי SendMessage בין סשנים, ושרתי Anthropic אימתו ששני הסשנים שייכים לאותה קבוצה פרטית של סשנים. דורש Claude Code מגרסה v2.1.224 ואילך. מסירה של send_message שהשרתים לא אימתו כך לא מקבלת subkind.

לכל התראת משימה אחרת אין subkind. זה כולל פעילות PR שנמסרת לתוך סשן ואירועי רקע כמו משימה שהסתיימה. הודעות מכלי SendMessage בין סשנים אינן התראות משימה בכלל: בין שהן מגיעות מסשן באותה מכונה ובין שהן מגיעות דרך שרתי Anthropic ממכונה אחרת, Claude Code נותן להן kind: "peer" ואת שדות המקור של peer.

fireReason אומר למה התראת scheduled-trigger הופעלה, כאסימון קצר באותיות קטנות כמו scheduled, manual, retry, catch_up או api. שרתי Anthropic מגדירים אותו על המסירות של משימה מתוזמנת בענן, והאפליקציה שלך מגדירה אותו כשהיא מצהירה על הרצה מתוזמנת. הוא נעדר כשאף אחד מהם לא שלח אותו. דורש TypeScript Agent SDK מגרסה v0.3.280 ואילך.

משימת רקע יכולה לרוץ יותר מפעם אחת תחת אותו task_id, למשל כש Claude ממשיך סוכן משנה. לכל הרצה יש run_id משלה. כשהתראה של הרצה מגיעה לסשן שלך כהודעת משתמש, runId על מקור ה task-notification של ההודעה הזו מחזיק את אותו ערך. התראה יכולה להגיע אחרי שההרצה הבאה של המשימה כבר התחילה, והיא עדיין נושאת את המזהה של ההרצה הקודמת. כדי לדעת לאיזו הרצה תור שייך, השוו את runId, לא את task_id. דורש TypeScript Agent SDK מגרסה v0.3.292 ואילך.

#הצהרה על הרצה מתוזמנת

אם האפליקציה שלך מריצה פרומפטים לפי לוח זמנים משלה, הכריזו על כל הרצה כדי ש Claude Code יציג את התור למודל כמשימה מתוזמנת ולא כקלט חי מהמשתמש. התחילו את הסשן עם CLAUDE_CODE_HOST_SCHEDULED_RUN שמוגדר ל 1 ב env, ואז שלחו את SDKUserMessage של ההרצה עם origin: { kind: "task-notification", subkind: "scheduled-trigger", fireReason: "scheduled" } ובלי isSynthetic. Claude Code מתעלם מההצהרה בתהליך שהופעל בלי המשתנה הזה. הוא גם מתעלם ממנה בתהליך שהסביבה שלו נושאת CLAUDECODE או CLAUDE_CODE_CHILD_SESSION. Claude Code שומר את fireReason רק כשהערך הוא 1 עד 32 אותיות קטנות או קווים תחתונים. דורש TypeScript Agent SDK מגרסה v0.3.280 ואילך.

#שדות מקור של peer

מקור peer מזהה איזה סוכן שלח את ההודעה: חבר צוות בתוך התהליך ששולח אל main עם SendMessage, או peer בין סשנים, אחד מסשני Claude Code האחרים שלך. peers בין סשנים דורשים Claude Code מגרסה v2.1.224 ואילך ב macOS וב Linux. ראו זמינות של הודעות בין סשנים לדרישה ב Windows מקורי. peer בין סשנים יכול לרוץ באותה מכונה, או באחת מהמכונות האחרות שלך כשההודעה שלו מגיעה דרך Remote Control.

• from: שם חבר הצוות, או כתובת השולח עבור peer בין סשנים. עבור הודעה חד כיוונית בין מכונות, לשולח אין כתובת לתשובה ו from הוא "unknown". הערך נכתב על ידי השולח. verifiedPeerPid הוא הזהות המאומתת.
• fromMode: מחלקת ההרשאות של הסשן השולח, bypass או prompting, שהוצהרה על ידי מארח שמעביר הודעת peer בין הסשנים שלך, כמו אפליקציית שולחן העבודה. Claude Code קורא אותו בסשן המקבל כשהוא מחיל את בקרות הכניסה. דורש Agent SDK מגרסה v0.3.234 ואילך.
• senderTaskId: מזהה המשימה של חבר הצוות. נעדר עבור peer בין סשנים.
• name: שם התצוגה של השולח, מנורמל על ידי Claude Code: הוא מסיר נקודות קוד של בקרת Unicode, פורמט, surrogate ומפרידי שורה או פסקה, ואז חותך את התוצאה ומגביל אותה ל 64 נקודות קוד עם אליפסיס. דורש Claude Code מגרסה v2.1.205 ואילך.
• body: גוף ההודעה המפוענח אחרי שהוסר מעטפת ה peer, מדויק בבייטים למה שהמודל רואה. נוכח עבור הודעה יחידה של חבר צוות, נעדר כשכמה הודעות ממוזגות. עבור peer בין סשנים, נוכח רק כשהתור הוא בדיוק מעטפת peer אחת שנוצרה על ידי Claude Code. רנדרו את name ואת body במקום לנתח מחדש את טקסט ההודעה. לפני v2.1.299, הודעות ממוזגות שמרו את body של ההודעה הראשונה. דורש Claude Code מגרסה v2.1.205 ואילך.
• fromSession: מזהה הסשן של השולח שאפשר לפתוח אצל המארח, שמוגדר על ידי המארח של השולח כדי שממשק המשתמש שלך יוכל לקשר חזרה לסשן השולח. כמו from, הוא נטען על ידי השולח: השתמשו בו רק כיעד ניווט, ואל תתייחסו אליו כהוכחה לזהות השולח. דורש Claude Code מגרסה v2.1.216 ואילך.
• verifiedPeerPid: מזהה התהליך של התהליך שהתחבר ל socket של הודעות בין סשנים של הסשן הזה, מאומת על ידי הקרנל ונקרא מהחיבור עצמו, אף פעם לא מה payload. השתמשו בו, לא ב from, כדי לזהות את השולח: from ניתן לזיוף על ידי כל תהליך של אותו משתמש. השדה נעדר כש Claude Code לא יכול לאמת אותו, למשל ב Windows או בכניסה שאינה socket, ולכן ערך נעדר אומר שהשולח לא מאומת. עבור תעבורה שמועברת דרך ממסר הוא מזהה את הממסר ולא את מחבר ההודעה, ומזהי תהליך ניתנים למחזור, אז התייחסו אליו כמקור ולא כאסימון אימות. דורש Claude Code מגרסה v2.1.216 ואילך.

#סוגי Hook

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

#HookEvent

אירועי hook זמינים.

type HookEvent =
  | "PreToolUse"
  | "PostToolUse"
  | "PostToolUseFailure"
  | "PostToolBatch"
  | "Notification"
  | "UserPromptSubmit"
  | "UserPromptExpansion"
  | "SessionStart"
  | "SessionEnd"
  | "Stop"
  | "StopFailure"
  | "SubagentStart"
  | "SubagentStop"
  | "PreCompact"
  | "PostCompact"
  | "PreModelSwitch"
  | "PostModelSwitch"
  | "PermissionRequest"
  | "PermissionDenied"
  | "Setup"
  | "TeammateIdle"
  | "TaskCreated"
  | "TaskCompleted"
  | "Elicitation"
  | "ElicitationResult"
  | "ConfigChange"
  | "DirectoryAdded"
  | "WorktreeCreate"
  | "WorktreeRemove"
  | "InstructionsLoaded"
  | "CwdChanged"
  | "FileChanged"
  | "MessageDisplay";

#HookCallback

טיפוס פונקציית callback של hook.

type HookCallback = (
  input: HookInput, // Union of all hook input types
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

#HookCallbackMatcher

תצורת hook עם matcher אופציונלי.

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
  timeout?: number; // Timeout in seconds for all hooks in this matcher
  onFailure?: "continue" | "block"; // "block" blocks the action when a callback fails
}

כדי להחליט מה onFailure מכסה, ראו חסימת הפעולה כש callback נכשל.

#HookInput

טיפוס איחוד של כל טיפוסי הקלט של hook.

type HookInput =
  | PreToolUseHookInput
  | PostToolUseHookInput
  | PostToolUseFailureHookInput
  | PostToolBatchHookInput
  | PermissionDeniedHookInput
  | NotificationHookInput
  | UserPromptSubmitHookInput
  | UserPromptExpansionHookInput
  | SessionStartHookInput
  | SessionEndHookInput
  | StopHookInput
  | StopFailureHookInput
  | SubagentStartHookInput
  | SubagentStopHookInput
  | PreCompactHookInput
  | PostCompactHookInput
  | PreModelSwitchHookInput
  | PostModelSwitchHookInput
  | PermissionRequestHookInput
  | SetupHookInput
  | TeammateIdleHookInput
  | TaskCreatedHookInput
  | TaskCompletedHookInput
  | ElicitationHookInput
  | ElicitationResultHookInput
  | ConfigChangeHookInput
  | InstructionsLoadedHookInput
  | DirectoryAddedHookInput
  | WorktreeCreateHookInput
  | WorktreeRemoveHookInput
  | CwdChangedHookInput
  | FileChangedHookInput
  | MessageDisplayHookInput;

#BaseHookInput

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

type BaseHookInput = {
  session_id: string;
  transcript_path: string;
  cwd: string;
  prompt_id?: string;
  permission_mode?: string;
  effort?: { level: string };
  agent_id?: string;
  agent_type?: string;
};

השדה prompt_id הוא UUID שמזהה את הנחיית המשתמש שמעובדת כרגע. הוא תואם למאפיין prompt.id באירועי OpenTelemetry והוא נעדר עד לקלט המשתמש הראשון. דורש Claude Code בגרסה v2.1.196 ואילך.

#PreToolUseHookInput

type PreToolUseHookInput = BaseHookInput & {
  hook_event_name: "PreToolUse";
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  mcp_server?: McpServerProvenance;
};

mcp_server קיים כשהכלי מגיע משרת MCP. ראו McpServerProvenance. הקלטים PostToolUse, PostToolUseFailure, PermissionRequest ו-PermissionDenied נושאים את אותו שדה. השדה דורש Agent SDK בגרסה v0.3.274 ואילך.

#PostToolUseHookInput

type PostToolUseHookInput = BaseHookInput & {
  hook_event_name: "PostToolUse";
  tool_name: string;
  tool_input: unknown;
  tool_response: unknown;
  tool_use_id: string;
  duration_ms?: number;
  mcp_server?: McpServerProvenance;
};

#PostToolUseFailureHookInput

type PostToolUseFailureHookInput = BaseHookInput & {
  hook_event_name: "PostToolUseFailure";
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  error: string;
  is_interrupt?: boolean;
  duration_ms?: number;
  mcp_server?: McpServerProvenance;
};

#PostToolBatchHookInput

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

type PostToolBatchHookInput = BaseHookInput & {
  hook_event_name: "PostToolBatch";
  tool_calls: PostToolBatchToolCall[];
};

type PostToolBatchToolCall = {
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  tool_response?: unknown;
};

#PermissionDeniedHookInput

type PermissionDeniedHookInput = BaseHookInput & {
  hook_event_name: "PermissionDenied";
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  reason: string;
  mcp_server?: McpServerProvenance;
};

#NotificationHookInput

type NotificationHookInput = BaseHookInput & {
  hook_event_name: "Notification";
  message: string;
  title?: string;
  notification_type: string;
};

#UserPromptSubmitHookInput

type UserPromptSubmitHookInput = BaseHookInput & {
  hook_event_name: "UserPromptSubmit";
  prompt: string;
  session_title?: string;
};

#UserPromptExpansionHookInput

type UserPromptExpansionHookInput = BaseHookInput & {
  hook_event_name: "UserPromptExpansion";
  expansion_type: "slash_command" | "mcp_prompt";
  command_name: string;
  command_args: string;
  command_source?: string;
  prompt: string;
};

#SessionStartHookInput

type SessionStartHookInput = BaseHookInput & {
  hook_event_name: "SessionStart";
  source: "startup" | "resume" | "clear" | "compact" | "fork";
  agent_type?: string;
  model?: string;
  session_title?: string;
};

#SessionEndHookInput

type SessionEndHookInput = BaseHookInput & {
  hook_event_name: "SessionEnd";
  reason: ExitReason; // String from EXIT_REASONS array
};

#StopHookInput

type StopHookInput = BaseHookInput & {
  hook_event_name: "Stop";
  stop_hook_active: boolean;
  last_assistant_message?: string;
  background_tasks?: BackgroundTaskSummary[];
  session_crons?: SessionCronSummary[];
};

#StopFailureHookInput

type StopFailureHookInput = BaseHookInput & {
  hook_event_name: "StopFailure";
  error: SDKAssistantMessageError;
  error_details?: string;
  last_assistant_message?: string;
};

#SubagentStartHookInput

type SubagentStartHookInput = BaseHookInput & {
  hook_event_name: "SubagentStart";
  agent_id: string;
  agent_type: string;
};

#SubagentStopHookInput

type SubagentStopHookInput = BaseHookInput & {
  hook_event_name: "SubagentStop";
  stop_hook_active: boolean;
  agent_id: string;
  agent_transcript_path: string;
  agent_type: string;
  last_assistant_message?: string;
  background_tasks?: BackgroundTaskSummary[];
  session_crons?: SessionCronSummary[];
};

type BackgroundTaskSummary = {
  id: string;
  type: string;
  status: string;
  description: string;
  command?: string;
  agent_type?: string;
  server?: string;
  tool?: string;
  name?: string;
};

type SessionCronSummary = {
  id: string;
  schedule: string;
  recurring: boolean;
  prompt: string;
};

#PreCompactHookInput

type PreCompactHookInput = BaseHookInput & {
  hook_event_name: "PreCompact";
  trigger: "manual" | "auto";
  custom_instructions: string | null;
};

#PostCompactHookInput

type PostCompactHookInput = BaseHookInput & {
  hook_event_name: "PostCompact";
  trigger: "manual" | "auto";
  compact_summary: string;
};

#PreModelSwitchHookInput

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

type PreModelSwitchHookInput = BaseHookInput & {
  hook_event_name: "PreModelSwitch";
  from_model: string;
  to_model: string;
  requested_model: string | null;
  source: "command" | "picker" | "sdk";
  context_tokens: number;
  prompt_cache_warm: boolean;
  cache_ttl: "5m" | "1h";
  estimated_cache_write_usd: number;
  pricing: "configured" | "catalog" | "default";
};

#PostModelSwitchHookInput

מופעל אחרי שמודל הסשן משתנה. הוא נושא את אותם שדות כמו PreModelSwitchHookInput, עם שני ערכי source נוספים. ראו PostModelSwitch.

type PostModelSwitchHookInput = BaseHookInput & {
  hook_event_name: "PostModelSwitch";
  from_model: string;
  to_model: string;
  requested_model: string | null;
  source: "command" | "picker" | "sdk" | "auto" | "resume";
  context_tokens: number;
  prompt_cache_warm: boolean;
  cache_ttl: "5m" | "1h";
  estimated_cache_write_usd: number;
  pricing: "configured" | "catalog" | "default";
};

#PermissionRequestHookInput

type PermissionRequestHookInput = BaseHookInput & {
  hook_event_name: "PermissionRequest";
  tool_name: string;
  tool_input: unknown;
  permission_suggestions?: PermissionUpdate[];
  mcp_server?: McpServerProvenance;
};

#SetupHookInput

type SetupHookInput = BaseHookInput & {
  hook_event_name: "Setup";
  trigger: "init" | "maintenance";
};

#TeammateIdleHookInput

type TeammateIdleHookInput = BaseHookInput & {
  hook_event_name: "TeammateIdle";
  teammate_name: string;
  /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */
  team_name: string;
};

#TaskCreatedHookInput

type TaskCreatedHookInput = BaseHookInput & {
  hook_event_name: "TaskCreated";
  task_id: string;
  task_subject: string;
  task_description?: string;
  teammate_name?: string;
  /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */
  team_name?: string;
};

#TaskCompletedHookInput

type TaskCompletedHookInput = BaseHookInput & {
  hook_event_name: "TaskCompleted";
  task_id: string;
  task_subject: string;
  task_description?: string;
  teammate_name?: string;
  /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */
  team_name?: string;
};

#ElicitationHookInput

type ElicitationHookInput = BaseHookInput & {
  hook_event_name: "Elicitation";
  mcp_server_name: string;
  message: string;
  mode?: "form" | "url";
  url?: string;
  elicitation_id?: string;
  requested_schema?: Record<string, unknown>;
};

#ElicitationResultHookInput

type ElicitationResultHookInput = BaseHookInput & {
  hook_event_name: "ElicitationResult";
  mcp_server_name: string;
  elicitation_id?: string;
  mode?: "form" | "url";
  action: "accept" | "decline" | "cancel";
  content?: Record<string, unknown>;
};

#ConfigChangeHookInput

type ConfigChangeHookInput = BaseHookInput & {
  hook_event_name: "ConfigChange";
  source:
    | "user_settings"
    | "project_settings"
    | "local_settings"
    | "policy_settings"
    | "skills";
  file_path?: string;
};

#InstructionsLoadedHookInput

type InstructionsLoadedHookInput = BaseHookInput & {
  hook_event_name: "InstructionsLoaded";
  file_path: string;
  memory_type: "User" | "Project" | "Local" | "Managed";
  load_reason:
    | "session_start"
    | "nested_traversal"
    | "path_glob_match"
    | "include"
    | "compact";
  globs?: string[];
  trigger_file_path?: string;
  parent_file_path?: string;
};

#DirectoryAddedHookInput

type DirectoryAddedHookInput = BaseHookInput & {
  hook_event_name: "DirectoryAdded";
  directory: string;
  source: "slash_command" | "register_repo_root";
};

directory הוא הנתיב המוחלט של התיקייה שנוספה. source הוא "slash_command" כש-/add-dir הוסיף אותה, ו-"register_repo_root" כשבקשת הבקרה של ה-SDK עשתה זאת.

#WorktreeCreateHookInput

type WorktreeCreateHookInput = BaseHookInput & {
  hook_event_name: "WorktreeCreate";
  name: string;
};

#WorktreeRemoveHookInput

type WorktreeRemoveHookInput = BaseHookInput & {
  hook_event_name: "WorktreeRemove";
  worktree_path: string;
};

#CwdChangedHookInput

type CwdChangedHookInput = BaseHookInput & {
  hook_event_name: "CwdChanged";
  old_cwd: string;
  new_cwd: string;
};

#FileChangedHookInput

type FileChangedHookInput = BaseHookInput & {
  hook_event_name: "FileChanged";
  file_path: string;
  event: "change" | "add" | "unlink";
};

#MessageDisplayHookInput

type MessageDisplayHookInput = BaseHookInput & {
  hook_event_name: "MessageDisplay";
  turn_id: string;
  message_id: string;
  index: number;
  final: boolean;
  delta: string;
};

#HookJSONOutput

ערך ההחזרה של הוק.

type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;

#AsyncHookJSONOutput

type AsyncHookJSONOutput = {
  async: true;
  asyncTimeout?: number;
};

#SyncHookJSONOutput

type SyncHookJSONOutput = {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: "approve" | "block";
  systemMessage?: string;
  /**
   * A terminal escape sequence (e.g. OSC 9 / OSC 777 desktop-notification)
   * for Claude Code to emit on your behalf. Only notification/title OSCs
   * (0, 1, 2, 9, 99, 777) and BEL are permitted; a value containing
   * anything else is ignored as a whole. Only the interactive CLI emits
   * it; the SDK ignores the field.
   */
  terminalSequence?: string;
  reason?: string;
  hookSpecificOutput?:
    | {
        hookEventName: "PreToolUse";
        permissionDecision?: "allow" | "deny" | "ask" | "defer";
        permissionDecisionReason?: string;
        updatedInput?: Record<string, unknown>;
        additionalContext?: string;
      }
    | {
        hookEventName: "UserPromptSubmit";
        additionalContext?: string;
        sessionTitle?: string;
        /** When decision is "block", omit the original prompt from the block message. */
        suppressOriginalPrompt?: boolean;
      }
    | {
        hookEventName: "UserPromptExpansion";
        additionalContext?: string;
      }
    | {
        hookEventName: "SessionStart";
        additionalContext?: string;
        initialUserMessage?: string;
        sessionTitle?: string;
        watchPaths?: string[];
        /**
         * Re-scan skill and command directories after SessionStart hooks
         * complete, so skills installed by the hook are available in the
         * same session.
         */
        reloadSkills?: boolean;
      }
    | {
        hookEventName: "Setup";
        additionalContext?: string;
      }
    | {
        hookEventName: "PreModelSwitch";
        /**
         * Same contract as PreToolUse: "allow" proceeds, "deny" cancels
         * the switch, "ask" asks the user to confirm. Only /model in an
         * interactive session shows that prompt; every other surface,
         * set_model requests included, treats "ask" as a refusal.
         */
        permissionDecision?: "allow" | "deny" | "ask";
        permissionDecisionReason?: string;
      }
    | {
        hookEventName: "PostModelSwitch";
        /** Reaches the model with the next request the new model serves. */
        additionalContext?: string;
      }
    | {
        hookEventName: "SubagentStart";
        additionalContext?: string;
      }
    | {
        hookEventName: "PostToolUse";
        additionalContext?: string;
        /**
         * Short note about this tool call's result for the auto mode
         * permission classifier. Capped at 2000 characters, shared across
         * all hooks that respond to the same call; honored on synchronous
         * hook responses only. Don't copy untrusted tool output into it.
         */
        classifierContext?: string;
        updatedToolOutput?: unknown;
        /** @deprecated Use `updatedToolOutput`, which works for all tools. */
        updatedMCPToolOutput?: unknown;
      }
    | {
        hookEventName: "PostToolUseFailure";
        additionalContext?: string;
      }
    | {
        hookEventName: "PostToolBatch";
        additionalContext?: string;
      }
    | {
        hookEventName: "Stop";
        additionalContext?: string;
      }
    | {
        hookEventName: "SubagentStop";
        additionalContext?: string;
      }
    | {
        hookEventName: "PermissionDenied";
        retry?: boolean;
      }
    | {
        hookEventName: "Notification";
        additionalContext?: string;
      }
    | {
        hookEventName: "PermissionRequest";
        decision:
          | {
              behavior: "allow";
              updatedInput?: Record<string, unknown>;
              updatedPermissions?: PermissionUpdate[];
            }
          | {
              behavior: "deny";
              message?: string;
              interrupt?: boolean;
            };
      }
    | {
        hookEventName: "Elicitation";
        action?: "accept" | "decline" | "cancel";
        content?: Record<string, unknown>;
      }
    | {
        hookEventName: "ElicitationResult";
        action?: "accept" | "decline" | "cancel";
        content?: Record<string, unknown>;
      }
    | {
        hookEventName: "CwdChanged";
        watchPaths?: string[];
      }
    | {
        hookEventName: "FileChanged";
        watchPaths?: string[];
      }
    | {
        hookEventName: "WorktreeCreate";
        worktreePath: string;
      }
    | {
        hookEventName: "MessageDisplay";
        /** Text displayed in place of the delta. Omit (or return the delta unchanged) to display the original. */
        displayContent?: string;
      };
};

#סוגי קלט של כלים

תיעוד של סכמות קלט לכלים המובנים של Claude Code. הטיפוסים האלה מיוצאים מ-@anthropic-ai/claude-agent-sdk/sdk-tools ואפשר להשתמש בהם לאינטראקציות בטוחות טיפוס עם כלים.

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

#ToolInputSchemas

איחוד של סוגי קלט של כלים שמיוצאים מ-@anthropic-ai/claude-agent-sdk/sdk-tools. החברים כוללים:

type ToolInputSchemas =
  | AgentInput
  | ArtifactInput
  | AskUserQuestionInput
  | BashInput
  | CronCreateInput
  | CronDeleteInput
  | CronListInput
  | EnterPlanModeInput
  | EnterWorktreeInput
  | ExitPlanModeInput
  | ExitWorktreeInput
  | FileEditInput
  | FileReadInput
  | FileWriteInput
  | GlobInput
  | GrepInput
  | ListMcpResourcesInput
  | McpInput
  | MonitorInput
  | NotebookEditInput
  | ProjectsInput
  | PushNotificationInput
  | ReadMcpResourceDirInput
  | ReadMcpResourceInput
  | RefreshMcpToolsInput
  | RemoteTriggerInput
  | ReportFindingsInput
  | ScheduleWakeupInput
  | ShowOnboardingRolePickerInput
  | TaskCreateInput
  | TaskGetInput
  | TaskListInput
  | TaskStopInput
  | TaskUpdateInput
  | TodoWriteInput
  | WebFetchInput
  | WebSearchInput
  | WorkflowInput;

#Agent

שם הכלי: Agent. השם הקודם Task עדיין מתקבל ככינוי כשהכלי זמין לסשן.

מערך tools בהודעת האתחול SDKSystemMessage מציג את הכלי הזה כ-Task לצורך תאימות לאחור.

[!NOTE]

השדה mode מיושן ומתעלמים ממנו ב-Claude Code מגרסה v2.1.212 ואילך. סוכן משנה רץ או במצב ההרשאות של סשן האב או ב-permissionMode של ההגדרה שלו, וכללי הירושה של סוכן משנה קובעים איזה מהם.

type AgentInput = {
  description: string;
  prompt: string;
  subagent_type?: string;
  model?: "sonnet" | "opus" | "haiku" | "fable";
  effort?: "low" | "medium" | "high" | "xhigh" | "max";
  run_in_background?: boolean;
  name?: string;
  team_name?: string; // Deprecated; ignored
  mode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan"; // Deprecated; ignored. The subagent inheritance rules decide a subagent's permission mode
  isolation?: "worktree" | "remote";
};

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

#AskUserQuestion

שם הכלי: AskUserQuestion

type AskUserQuestionInput = {
  questions: Array<{
    question: string;
    header: string;
    options: Array<{ label: string; description: string; preview?: string }>;
    multiSelect: boolean;
  }>;
  answers?: Record<string, string>;
  annotations?: Record<string, { preview?: string; notes?: string }>;
  metadata?: { source?: string };
};

שואל את המשתמש שאלות הבהרה במהלך הביצוע. ראו טיפול באישורים ובקלט משתמש לפרטי השימוש.

#Bash

שם הכלי: Bash

type BashInput = {
  command: string;
  timeout?: number; // milliseconds. Foreground: capped at 600000 by default, higher values are clamped. With run_in_background (Claude Code v2.1.285 or later): the background time limit, 1800000 when omitted, capped at 7200000 unless raised
  description?: string;
  run_in_background?: boolean;
  dangerouslyDisableSandbox?: boolean;
};

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

#Monitor

שם הכלי: Monitor

type MonitorInput = {
  description: string;
  timeout_ms: number;
  command?: string;
  ws?: {
    url: string;
    protocols?: string[];
  };
};

מריץ מקור רקע ומעביר כל אירוע ל-Claude כדי שיוכל להגיב בלי סקרים: command מריץ סקריפט ופולט אירוע אחד לכל שורת stdout, ו-ws פותח WebSocket ופולט אירוע אחד לכל מסגרת טקסט. יש לספק בדיוק אחד מבין command או ws. מקור ws דורש Claude Code מגרסה v2.1.195 ואילך.

timeout_ms הוא מועד הסיום של המעקב במילישניות. ברירת המחדל היא 300000, והוא מקבל ערכים עד 3600000. המועד האפקטיבי הוא לכל היותר 1800000, כלומר 30 דקות, ולכן ערך גדול יותר שמתקבל מקוצר לכך. במועד הסיום המעקב מסתיים ו-Claude מקבל הודעה אחת כדי שיוכל להתחיל מעקב חדש אם הוא עדיין צריך.

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

כש-Monitor מריץ פקודה, הוא פועל לפי אותם כללי הרשאות כמו Bash. מעקב WebSocket מבקש אישור בנפרד. ראו את הפניה לכלי Monitor להתנהגות ולזמינות ספקים.

#TaskOutput

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

רשומת disallowedTools או כלל deny שעדיין מציין TaskOutput מתעלמים ממנו בלי אזהרה.

#Edit

שם הכלי: Edit

type FileEditInput = {
  file_path: string;
  old_string: string;
  new_string: string;
  replace_all?: boolean;
};

מבצע החלפות מחרוזת מדויקות בקבצים.

#Read

שם הכלי: Read

type FileReadInput = {
  file_path: string;
  offset?: number;
  limit?: number;
  pages?: string;
  allow_large?: boolean;
};

קורא קבצים ממערכת הקבצים המקומית, כולל טקסט, תמונות, PDF ומחברות Jupyter.

• השתמשו ב-pages לטווחי עמודים ב-PDF (לדוגמה, "1-5").
• allow_large מאפשר ל-Claude לקרוא קובץ טקסט מעבר למגבלות הגודל הרגילות כשיש מקום בחלון ההקשר של הסשן. זה דורש Agent SDK מגרסה v0.3.296 ואילך, שכולל את Claude Code מגרסה v2.1.296.

עבור PDF, Claude מקבל את תוכן הקובץ בתוך תוכן tool_result של קריאת ה-Read. קריאה שמחזירה את הפלט pdf נושאת בלוק text של סיכום ואחריו בלוק document. קריאה שמחזירה את פלט parts נושאת את בלוק text של הסיכום ואחריו בלוק אחד לכל עמוד שחולץ: בלוק image, או בלוק text שמציין את העמוד כש-Claude Code לא הצליח לרנדר אותו כתמונה. לפני Agent SDK מגרסה v0.3.242, Claude Code העביר את תוכן הקובץ כהודעת user נפרדת אחרי תוצאת הכלי.

#Write

שם הכלי: Write

type FileWriteInput = {
  file_path: string;
  content: string;
};

כותב קובץ למערכת הקבצים המקומית, ודורס אם הוא קיים.

#Glob

שם הכלי: Glob

type GlobInput = {
  pattern: string;
  path?: string;
};

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

#Grep

שם הכלי: Grep

type GrepInput = {
  pattern: string;
  path?: string;
  glob?: string;
  type?: string;
  output_mode?: "content" | "files_with_matches" | "count";
  "-i"?: boolean;
  "-o"?: boolean; // print only the matched parts of each line; requires output_mode: "content"
  "-n"?: boolean;
  "-B"?: number;
  "-A"?: number;
  "-C"?: number;
  context?: number;
  head_limit?: number;
  offset?: number;
  multiline?: boolean;
};

כלי חיפוש שנבנה על ripgrep עם תמיכה בביטויים רגולריים.

#TaskStop

שם הכלי: TaskStop

type TaskStopInput = {
  task_id?: string;
  shell_id?: string; // Deprecated: use task_id
};

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

#NotebookEdit

שם הכלי: NotebookEdit

type NotebookEditInput = {
  notebook_path: string;
  cell_id?: string;
  new_source: string;
  cell_type?: "code" | "markdown";
  edit_mode?: "replace" | "insert" | "delete";
};

עורך תאים בקבצי מחברת Jupyter.

#WebFetch

שם הכלי: WebFetch

type WebFetchInput = {
  url: string;
  prompt: string;
  offset?: number;
};

מביא תוכן מכתובת URL ומעבד אותו עם מודל AI.

offset הוא מספר התווים לדלג מתחילת העמוד. Claude מגדיר אותו כדי להמשיך לקרוא עמוד ארוך. השדה דורש Agent SDK מגרסה v0.3.290 ואילך.

#WebSearch

שם הכלי: WebSearch

type WebSearchInput = {
  query: string;
  allowed_domains?: string[];
  blocked_domains?: string[];
};

מחפש באינטרנט ומחזיר תוצאות מעוצבות.

#Workflow

שם הכלי: Workflow

type WorkflowInput = {
  script?: string;
  name?: string;
  scriptPath?: string;
  args?: unknown; // any JSON value; the published typings render this as an object map
  resumeFromRunId?: string;
  title?: string; // ignored; the script's meta block sets the title
  description?: string; // ignored; the script's meta block sets the description
};

מריץ תהליך עבודה דינמי: סקריפט שמתזמר סוכני משנה רבים ברקע ומחזיר תוצאה מאוחדת אחת. הכלי Workflow זמין ב-Agent SDK מגרסה v0.3.149 ואילך. נדרש לפחות אחד מבין script, name או scriptPath.

#TodoWrite

שם הכלי: TodoWrite

type TodoWriteInput = {
  todos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
};

יוצר ומנהל רשימת משימות מובנית למעקב אחר התקדמות.

[!NOTE]

הכלים הבאים זמינים כברירת מחדל רק ב-Claude Opus 4.7, Claude Sonnet 4.6, Claude Haiku 4.5, ובמודלים מוקדמים יותר. בכל מודל אחר, כולל מזהי מודל ש-Claude Code לא מזהה, הם לא זמינים אלא אם בוחרים להצטרף:

• TodoWrite
• TaskCreate
• TaskGet
• TaskUpdate
• TaskList

בכל מקום שהכלים זמינים, Claude Code מספק את ארבעת כלי ה-Task, או את TodoWrite במקום כשמגדירים CLAUDE_CODE_ENABLE_TASKS=0.

ערכת ברירת המחדל הזו חלה ב-Claude Code מגרסה v2.1.268 ואילך, שה-TypeScript Agent SDK כולל החל מגרסה v0.3.268.

ראו זמינות מודלים כדי להצטרף.

#TaskCreate

שם הכלי: TaskCreate

type TaskCreateInput = {
  subject: string;
  description: string;
  activeForm?: string;
  metadata?: Record<string, unknown>;
};

יוצר משימה אחת ומחזיר את המזהה שהוקצה לה.

#TaskUpdate

שם הכלי: TaskUpdate

type TaskUpdateInput = {
  taskId: string;
  status?: "pending" | "in_progress" | "completed" | "deleted";
  subject?: string;
  description?: string;
  activeForm?: string;
  addBlocks?: string[];
  addBlockedBy?: string[];
  owner?: string;
  metadata?: Record<string, unknown>;
};

מעדכן משימה אחת לפי מזהה. הגדירו את status ל-"deleted" כדי להסיר אותה.

#TaskGet

שם הכלי: TaskGet

type TaskGetInput = {
  taskId: string;
};

מחזיר פרטים מלאים למשימה אחת, או null כשהמזהה לא נמצא.

#TaskList

שם הכלי: TaskList

type TaskListInput = {};

מחזיר תמונת מצב של כל המשימות ברשימה הנוכחית.

#ExitPlanMode

שם הכלי: ExitPlanMode

type ExitPlanModeInput = {
  /** Deprecated: no longer used. */
  allowedPrompts?: Array<{
    tool: "Bash";
    prompt: string;
  }>;
  [k: string]: unknown;
};

יוצא ממצב תוכנית. השדה allowedPrompts מיושן ומתעלמים ממנו. Claude Code עדיין מקבל אותו כדי שקוראים קיימים ותמלילים יעברו אימות. לפני גרסה v2.1.205, הוא ביקש הרשאות Bash מבוססות prompt ליישום התוכנית.

#ListMcpResources

שם הכלי: ListMcpResourcesTool

type ListMcpResourcesInput = {
  server?: string;
};

מציג משאבי MCP זמינים משרתים מחוברים.

#ReadMcpResource

שם הכלי: ReadMcpResourceTool

type ReadMcpResourceInput = {
  server: string;
  uri: string;
};

קורא משאב MCP מסוים משרת.

#EnterWorktree

שם הכלי: EnterWorktree

type EnterWorktreeInput = {
  name?: string;
  path?: string;
};

יוצר ונכנס ל-git worktree זמני לעבודה מבודדת. העבירו path כדי לעבור ל-worktree קיים במקום ליצור חדש. בכניסה הראשונה היעד חייב להיות worktree רשום של המאגר הנוכחי או, בסביבת עבודה מרובת מאגרים, של מאגר מקונן בתוכו. מתוך סשן worktree הוא חייב להיות תחת .claude/worktrees/ של מאגר הסשן. name ו-path מוציאים זה את זה.

#ExitWorktree

שם הכלי: ExitWorktree

type ExitWorktreeInput = {
  action: "keep" | "remove";
  discard_changes?: boolean;
};

יוצא מה-git worktree הנוכחי וחוזר לספריית העבודה המקורית. הפעולה keep משאירה את ה-worktree ואת הענף בדיסק, ו-remove מוחק את שניהם. discard_changes חייב להיות true כשמסירים worktree שיש בו קבצים שלא בוצע להם commit או commits שלא מוזגו.

#EnterPlanMode

שם הכלי: EnterPlanMode

type EnterPlanModeInput = {};

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

#CronCreate

שם הכלי: CronCreate

type CronCreateInput = {
  cron: string;
  prompt: string;
  recurring?: boolean;
  durable?: boolean;
};

מתזמן prompt לרוץ לפי לוח cron בן 5 שדות בזמן מקומי. הגדירו את recurring ל-false כדי להפעיל פעם אחת בהתאמה הבאה. משימות הן בהיקף הסשן כברירת מחדל, וחידוש עם --resume או --continue משחזר משימות שטרם פגו. ראו משימות מתוזמנות בהיקף סשן.

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

#CronDelete

שם הכלי: CronDelete

type CronDeleteInput = {
  id: string;
};

מוחק משימת cron מתוזמנת לפי המזהה שהוחזר מ-CronCreate.

#CronList

שם הכלי: CronList

type CronListInput = {};

מציג את משימות ה-cron המתוזמנות: משימות עמידות מ-.claude/scheduled_tasks.json ומשימות לסשן בלבד מהסשן הנוכחי.

#ScheduleWakeup

שם הכלי: ScheduleWakeup

type ScheduleWakeupInput = {
  delaySeconds?: number;
  reason?: string;
  prompt?: string;
  noop?: boolean;
  stop?: boolean;
};

מתזמן התעוררות חד פעמית שמפעילה את ה-prompt הנתון אחרי השהיה. הכלי הזה עומד מאחורי הפקודה /loop בקצב עצמי. סביבת הריצה מצמצמת את delaySeconds לטווח שבין 60 ל-3600 שניות. השדות delaySeconds, reason, prompt ו-noop נדרשים אלא אם stop הוא true. noop: true מדווח על התעוררות שבה שום דבר לא השתנה. הגדרת stop: true מבטלת את ההתעוררות הממתינה ומסיימת את /loop בקצב העצמי. השדה stop דורש Claude Code מגרסה v2.1.202 ואילך. ראו את שורת ScheduleWakeup בהפניה לכלים.

#RemoteTrigger

שם הכלי: RemoteTrigger

type RemoteTriggerInput = {
  action:
    | "list"
    | "get"
    | "create"
    | "update"
    | "run"
    | "create_webhook_trigger"
    | "list_runs"
    | "get_run_log";
  trigger_id?: string;
  session_id?: string;
  cursor?: string;
  body?: {
    [k: string]: unknown;
  };
};

מנהל משימות מתוזמנות בענן, שנקראו בעבר routines: הריצות המתוזמנות והמופעלות של Claude Code שמתארחות בענן. הכלי הזה עומד מאחורי הפקודה /schedule. trigger_id נדרש לפעולות get, update, run ו-list_runs. body נדרש ל-create, update ו-create_webhook_trigger, ואופציונלי ל-run.

create_webhook_trigger, list_runs ו-get_run_log דורשים כל אחד גרסת מינימום של Claude Code:

• create_webhook_trigger: מחבר מקור אירועים למשימה מתוזמנת קיימת, כגון אירוע GitHub שמפעיל אותה. ה-body נותן שם למקור, לאירועים ולמשימה להפעלה. דורש Claude Code v2.1.225 או מאוחר יותר.
• list_runs ו-get_run_log: list_runs מציג את הריצות האחרונות של משימה מתוזמנת, ו-get_run_log קורא את היומן של ריצה אחת. session_id מציין את הריצה לקריאה, מתוך תוצאת list_runs, ו-cursor מדפדף בתוצאות של כל אחת מהפעולות. שתי הפעולות דורשות Claude Code v2.1.227 או מאוחר יותר.

הכלי זמין רק כשהסשן מאומת עם חשבון claude.ai בתוכנית שבה משימות מתוזמנות בענן מופעלות. הוא נעדר כשמדיניות הארגון משביתה סשנים בענן. ב-Claude Code v2.1.227 או מאוחר יותר, הכלי נעדר גם כש-Owner כיבה משימות מתוזמנות עבור הארגון.

#PushNotification

שם הכלי: PushNotification

type PushNotificationInput = {
  message: string;
  status: "proactive";
};

שולח התראת דחיפה יזומה למשתמש. שמור את message מתחת ל-200 תווים, כי מערכות הפעלה לנייד חותכות טקסט ארוך יותר. ראה את השורה PushNotification במדריך הכלים לזמינות ספקים. מסירת הדחיפה רצה דרך תשתית שמתארחת ב-Anthropic, שאינה נגישה מ-Amazon Bedrock, Claude Platform on AWS, Google Cloud's Agent Platform, או Microsoft Foundry.

#REPL

הוסר ב-v2.1.275. עד v2.1.274, כלי REPL ניסיוני אפשר היה להפעיל עם CLAUDE_CODE_REPL=1 באפשרות env.

#ReportFindings

שם הכלי: ReportFindings

type ReportFindingsInput = {
  level?: "low" | "medium" | "high" | "xhigh" | "max";
  findings: Array<{
    file: string;
    line?: number;
    summary: string;
    failure_scenario: string;
    short_summary?: string;
    category?: string;
    verdict?: "CONFIRMED" | "PLAUSIBLE";
    outcome?: "fixed" | "skipped" | "no_change_needed";
  }>;
};

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

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

כל ממצא נושא את השדות האלה:

• file: נתיב יחסי למאגר שבו נמצא הממצא. line האופציונלי הוא השורה באינדקס 1 שאליה הוא מעוגן.
• summary: משפט אחד על הפגם. failure_scenario מתאר את הקלטים והמצב הקונקרטיים שמובילים לפלט השגוי או לקריסה.
• short_summary: תווית דחוסה אופציונלית של לכל היותר 60 תווים לתצוגה קומפקטית. דורש Claude Code v2.1.212 או מאוחר יותר.
• category: slug קצר אופציונלי ב-kebab-case של סוג הממצא, כגון correctness או test-coverage. דורש Claude Code v2.1.199 או מאוחר יותר.
• verdict: מוגדר כשריצת אימות רצה. נעדר בסקירות inline בלבד.
• outcome: מוגדר רק כשמדווחים מחדש אחרי החלת תיקונים.

#Artifact

שם הכלי: Artifact

type ArtifactInput = {
  action?: "publish" | "list";
  file_path?: string;
  favicon?: string;
  icon?: string;
  limit?: number;
  scope?: "mine" | "shared" | "all";
  title?: string;
  description?: string;
  label?: string;
  url?: string;
  force?: boolean;
  capabilities?: Record<string, unknown>;
  contract?: "latest" | string;
};

מפרסם קובץ .html או .md מקומי כעמוד artifact מתארח, או מציג את ה-artifacts שפורסמו של המשתמש. השמט את action או העבר "publish" כדי לפרסם את file_path, שנדרש לפעולת הפרסום. כל שדה למטה חל על פרסום:

• icon: מילה גנרית קצרה אחת לאייקון לשונית הדפדפן של ה-artifact, כגון chart או map. Claude כולל אותה בפרסום ראשון ומשמיט אותה בעדכון, מה ששומר על האייקון השמור של ה-artifact.
• favicon: deprecated, ו-Claude משמיט אותו.
• title: נותן שם לעמוד שפורסם בלשונית הדפדפן ובגלריה כשלקובץ ה-HTML אין תג <title>.
• url: מכוון ל-artifact קיים לעדכון במקום, במקום יצירת אחד חדש.

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

העבר "list" כדי למנות את ה-artifacts שפורסמו של המשתמש. רק limit ו-scope יכולים להתלוות אליו. scope ברירת המחדל היא "mine", שמציג artifacts שהמשתמש הוא הבעלים שלהם. "shared" מציג artifacts שאנשים אחרים שיתפו עם המשתמש, ו-"all" מציג את שניהם.

limit קובע את המספר המרבי של artifacts שרשימה מחזירה, מ-1 עד 200. limit מעל 50 דורש Agent SDK v0.3.292 או מאוחר יותר. בלי limit, רשימה מחזירה עד 25.

• capabilities: יכולות זמן הריצה שעמוד שפורסם משתמש בהן, לפי שם היכולת, כגון המחברים שהעמוד רשאי לקרוא. שירות ה-artifact מאמת את ההצהרה ודוחה פרסום שנותן שם ליכולת שהחשבון לא יכול להשתמש בה, או נותן לאחת הגדרה לא תקינה. העבר {} כדי לנקות הצהרה שמורה, והשמט את השדה בפריסה מחדש כדי לשמור אותה. דורש Agent SDK v0.3.235 או מאוחר יותר.
• contract: גרסת זמן הריצה שעמוד שפורסם רץ מולה. השמט אותו כדי לשמור את הגרסה הנוכחית של ה-artifact, העבר "latest" כדי לשדרג, או העבר גרסה ספציפית כדי לנעוץ או לחזור אחורה. דורש Agent SDK v0.3.235 או מאוחר יותר.

הטיפוסים מיוצאים, אבל הכלי כבוי כברירת מחדל בסשנים של Agent SDK. פרסום דורש גם כל תנאי בטבלת זמינות ה-artifacts, שסשנים שמאומתים עם מפתח API לא עומדים בהם.

#Projects

שם הכלי: Projects

type ProjectsInput = {
  method:
    | "project_info"
    | "project_read"
    | "project_search"
    | "project_write"
    | "project_delete";
  path?: string;
  content?: string;
  local_path?: string;
  present_to_user?: boolean;
  query?: string;
  n?: number;
};

קורא וכותב את ה-Project של claude.ai שמחובר לסשן. מנתב לפי method:

• project_info: מחזיר מטא נתונים של הפרויקט ואת רשימת המסמכים.
• project_read: קורא מסמך אחד לפי path.
• project_search: שואל את בסיס הידע של הפרויקט עם query. n מגביל את הפגיעות וברירת המחדל היא 5.
• project_write: יוצר או מחליף מסמך ב-path מאחד בדיוק מבין content, שנושא טקסט מוטמע, או local_path, שמציין קובץ בתוך ספריית העבודה. present_to_user: true מסמן את המסמך שנכתב כתוצר שהמשתמש צריך לראות.
• project_delete: מוחק מסמך לפי path.

#ReadMcpResourceDir

שם הכלי: ReadMcpResourceDirTool

type ReadMcpResourceDirInput = {
  server: string;
  uri: string;
};

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

#RefreshMcpTools

שם הכלי: RefreshMcpTools

type RefreshMcpToolsInput = {
  server?: string; // refresh only this server; omit to refresh all connected servers
};

שואל מחדש את רשימת הכלים של שרתי MCP מחוברים ומחיל כל שינוי. הטיפוסים מיוצאים, אבל Claude Code רושם את הכלי רק כשמגדירים CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS=1 באפשרות env, ורק בסשנים עם לפחות שרת MCP אחד. דורש Claude Code v2.1.211 או מאוחר יותר.

#ShowOnboardingRolePicker

שם הכלי: ShowOnboardingRolePicker

type ShowOnboardingRolePickerInput = {};

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

#McpInput

שם הכלי: שמות כלי MCP דינמיים בצורה mcp__<server>__<tool>

type McpInput = {
  [k: string]: unknown;
};

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

#סוגי פלט של כלים

תיעוד של סכמות פלט לכלים המובנים של Claude Code. הטיפוסים האלה מיוצאים מ-@anthropic-ai/claude-agent-sdk/sdk-tools ומייצגים את נתוני התגובה בפועל שכל כלי מחזיר.

#ToolOutputSchemas

איחוד של טיפוסי פלט כלים שמיוצאים מ-@anthropic-ai/claude-agent-sdk/sdk-tools. החברים כוללים:

type ToolOutputSchemas =
  | AgentOutput
  | ArtifactOutput
  | AskUserQuestionOutput
  | BashOutput
  | CronCreateOutput
  | CronDeleteOutput
  | CronListOutput
  | EnterPlanModeOutput
  | EnterWorktreeOutput
  | ExitPlanModeOutput
  | ExitWorktreeOutput
  | FileEditOutput
  | FileReadOutput
  | FileWriteOutput
  | GlobOutput
  | GrepOutput
  | ListMcpResourcesOutput
  | McpOutput
  | MonitorOutput
  | NotebookEditOutput
  | ProjectsOutput
  | PushNotificationOutput
  | ReadMcpResourceDirOutput
  | ReadMcpResourceOutput
  | RefreshMcpToolsOutput
  | RemoteTriggerOutput
  | ReportFindingsOutput
  | ScheduleWakeupOutput
  | ShowOnboardingRolePickerOutput
  | TaskCreateOutput
  | TaskGetOutput
  | TaskListOutput
  | TaskStopOutput
  | TaskUpdateOutput
  | TodoWriteOutput
  | WebFetchOutput
  | WebSearchOutput
  | WorkflowOutput;

#Agent

שם הכלי: Agent. השם הקודם Task עדיין מתקבל ככינוי כשהכלי הזה זמין לסשן.

type AgentOutput =
  | {
      status: "completed";
      agentId: string;
      agentType?: string;
      content: Array<{ type: "text"; text: string; citations?: unknown[] | null }>;
      resolvedModel?: string;
      modelsUsed?: string[];
      totalToolUseCount: number;
      totalDurationMs: number;
      totalTokens: number;
      usage: {
        input_tokens: number;
        output_tokens: number;
        cache_creation_input_tokens: number | null;
        cache_read_input_tokens: number | null;
        server_tool_use: {
          web_search_requests: number;
          web_fetch_requests: number;
        } | null;
        service_tier: string | null;
        cache_creation: {
          ephemeral_1h_input_tokens: number;
          ephemeral_5m_input_tokens: number;
        } | null;
        inference_geo?: string | null;
        speed?: string | null;
        iterations?: unknown;
        output_tokens_details?: {
          thinking_tokens?: number | null;
        } | null;
        fallback_credit?: unknown;
      };
      toolStats?: {
        readCount: number;
        searchCount: number;
        bashCount: number;
        editFileCount: number;
        linesAdded: number;
        linesRemoved: number;
        otherToolCount: number;
        frameCount?: number;
      };
      prompt: string;
      worktreePath?: string;
      worktreeBranch?: string;
    }
  | {
      status: "async_launched";
      isAsync?: true;
      agentId: string;
      description: string;
      resolvedModel?: string;
      modelsUsed?: string[];
      prompt: string;
      outputFile: string;
      canReadOutputFile?: boolean;
    }
  | {
      status: "remote_launched";
      taskId: string;
      sessionUrl: string;
      description: string;
      prompt: string;
      outputFile: string;
    };

מחזיר את התוצאה מסוכן המשנה. מובחן לפי שדה status: "completed" למשימות שהסתיימו, "async_launched" למשימות רקע, ו-"remote_launched" למשימות ש-Claude Code שיגר לסשן ענן, שבו sessionUrl מקשר לסשן הזה ו-taskId מזהה אותו.

בווריאנט completed, resolvedModel מציין את המודל שסוכן המשנה התחיל עליו, שיכול להיות שונה מקלט model המבוקש כש-availableModels או דריסה אחרת חלים. השדה הזה דורש Claude Code v2.1.174 או מאוחר יותר. ב-async_launched, הוא מציין את המודל שבשימוש כשהמשימה עברה לרקע.

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

אם Claude Code שמר את עץ העבודה המבודד של סוכן המשנה, worktreePath בתוצאת completed הוא המקום למצוא אותו. worktreeBranch הוא הענף שלו, נוכח כש-Claude Code יצר את עץ העבודה עם git.

Claude Code ממלא את usage ו-totalTokens מבקשת ה-API הסופית של סוכן המשנה, לא מכל הריצה, כך ש-usage.service_tier הוא מחרוזת שכבת השירות שה-API דיווח עליה בבקשה הזו. כשנוכח, usage.output_tokens_details.thinking_tokens הוא מספר טוקני הפלט של הבקשה הזו שהיו טוקני חשיבה. השדה output_tokens_details דורש TypeScript SDK v0.3.228 או מאוחר יותר, שכולל את Claude Code v2.1.228. השדה fallback_credit דורש TypeScript SDK v0.3.285 או מאוחר יותר, שכולל את Claude Code v2.1.285.

usage.output_tokens_details תואם במשמעות ל-Usage.output_tokens_details, בהיקף של הבקשה הסופית הזו, אבל כל רמה שלו אופציונלית כאן. הגן גם על האובייקט וגם על השדה, לדוגמה usage.output_tokens_details?.thinking_tokens ?? 0, במקום לקרוא אותו ישירות.

לפני v2.1.207, הטיפוס שפורסם היה צר יותר. הוא השמיט את worktreePath, worktreeBranch, citations, toolStats.frameCount, ואת שדות השימוש inference_geo, speed ו-iterations, והגדיר את הטיפוס של service_tier כ-"standard" | "priority" | "batch". שדות שהטיפוס מסמן כאופציונליים יכולים להיעדר בתוצאות שהוקלטו על ידי גרסאות מוקדמות יותר.

#AskUserQuestion

שם הכלי: AskUserQuestion

type AskUserQuestionOutput = {
  questions: Array<{
    question: string;
    header: string;
    options: Array<{ label: string; description: string; preview?: string }>;
    multiSelect: boolean;
  }>;
  answers: Record<string, string>;
  response?: string;
  annotations?: Record<string, { preview?: string; notes?: string }>;
  afkTimeoutMs?: number;
};

מחזיר את השאלות שנשאלו ואת התשובות של המשתמש. response מוגדר כשהמשתמש הקליד תשובה חופשית במקום לענות על השאלות המובנות. כשנוכח, Claude מקבל "The user responded: …" במקום רשימת התשובות לכל שאלה.

#Bash

שם הכלי: Bash

type BashOutput = {
  stdout: string;
  stderr: string;
  rawOutputPath?: string;
  interrupted: boolean;
  isImage?: boolean;
  backgroundTaskId?: string;
  backgroundedByUser?: boolean;
  timedOutAfterMs?: number;
  backgroundCwdHint?: string;
  backgroundEndsWithFinalResponse?: true;
  dangerouslyDisableSandbox?: boolean;
  returnCodeInterpretation?: string;
  noOutputExpected?: boolean;
  structuredContent?: unknown[];
  persistedOutputPath?: string;
  persistedOutputSize?: number;
  staleReadFileStateHint?: string;
  ghRateLimitHint?: string;
  gitOperation?: {
    commit?: { sha: string; kind: "committed" | "amended" | "cherry-picked"; branch?: string };
    push?: { branch: string };
    branch?: { ref: string; action: "merged" | "rebased" };
    pr?: {
      number: number;
      url?: string;
      action: "created" | "edited" | "merged" | "commented" | "closed" | "reopened" | "ready" | "draft" | "auto-merge-enabled" | "auto-merge-disabled";
    };
  };
};

השדות stdout, stderr ו-backgroundTaskId נושאים:

timedOutAfterMs הוא הזמן הקצוב באלפיות שנייה, והוא מוגדר כאשר הפקודה הגיעה לזמן הקצוב שלה ועברה לרקע במקום להתחיל שם במפורש. backgroundCwdHint מוגדר כאשר הפקודה שהועברה לרקע כללה builtin לשינוי תיקייה כגון cd, pushd, popd או chdir, ומציין שתיקיית העבודה של הסשן לא השתנתה. שני השדות דורשים Claude Code v2.1.210 או חדש יותר.

כאשר subagent שרץ בחזית מחזיק בפקודה שהועברה לרקע, הפקודה מסתיימת כאשר הריצה של אותו subagent מסתיימת. Claude Code מגדיר את backgroundEndsWithFinalResponse ל-true בפקודות כאלה, ומשמיט את השדה כאשר הפקודה שורדת את התור, כפי שעושות פקודות שהתחילו על ידי השיחה הראשית או על ידי subagents ברקע. השדה דורש Claude Code v2.1.227 או חדש יותר.

Claude Code מגדיר את gitOperation.commit.branch לענף ששמו מופיע בשורת סיכום ה-commit של git, ומשמיט אותו עבור commit שנעשה על detached HEAD. השדה דורש Agent SDK v0.3.227 או חדש יותר. Claude Code מדווח על פקודת gh pr reopen כפעולת PR מסוג reopened, מה שדורש Agent SDK v0.3.234 או חדש יותר.

#Monitor

שם הכלי: Monitor

type MonitorOutput = {
  taskId: string;
  timeoutMs: number;
  persistent?: boolean;
};

מחזיר את מזהה משימת הרקע של ה-monitor הרץ. השתמשו במזהה זה עם TaskStop כדי לבטל את המעקב מוקדם.

#Edit

שם הכלי: Edit

type FileEditOutput = {
  filePath: string;
  oldString: string;
  newString: string;
  originalFile: string | null;
  structuredPatch: Array<{
    oldStart: number;
    oldLines: number;
    newStart: number;
    newLines: number;
    lines: string[];
  }>;
  userModified: boolean;
  replaceAll: boolean;
  gitDiff?: {
    filename: string;
    status: "modified" | "added";
    additions: number;
    deletions: number;
    changes: number;
    patch: string;
    repository?: string | null;
  };
};

מחזיר את ה-diff המובנה של פעולת העריכה.

#Read

שם הכלי: Read

type FileReadOutput =
  | {
      type: "text";
      file: {
        filePath: string;
        content: string;
        numLines: number;
        startLine: number;
        totalLines: number;
        /** True when a whole-file read was auto-paginated because it exceeded the token cap (the content is a partial first page). */
        truncatedByTokenCap?: boolean;
      };
    }
  | {
      type: "image";
      file: {
        base64: string;
        type: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
        originalSize: number;
        dimensions?: {
          originalWidth?: number;
          originalHeight?: number;
          displayWidth?: number;
          displayHeight?: number;
        };
      };
    }
  | {
      type: "notebook";
      file: {
        filePath: string;
        cells: unknown[];
      };
    }
  | {
      type: "pdf";
      file: {
        filePath: string;
        base64: string;
        originalSize: number;
      };
    }
  | {
      type: "parts";
      file: {
        filePath: string;
        originalSize: number;
        count: number;
        outputDir: string;
      };
      /** Document page number of the first extracted page; labels the page images in the tool_result content. */
      firstPage?: number;
      /** In-process only: the page-image bytes are delivered as image blocks in the tool_result content and aren't retained on the emitted tool_use_result, so this key is absent there. */
      pages?: {
        base64: string;
        mediaType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
        error?: string;
      }[];
    }
  | {
      type: "file_unchanged";
      file: {
        filePath: string;
      };
      /** Set when the dedup matched a startup-seeded entry (CLAUDE.md / nested memory) rather than a prior Read tool_result. */
      source?: "seeded";
    };

מחזיר את תוכן הקובץ בפורמט המתאים לסוג הקובץ. מובחן לפי השדה type.

#Write

שם הכלי: Write

type FileWriteOutput = {
  type: "create" | "update";
  filePath: string;
  content: string;
  structuredPatch: Array<{
    oldStart: number;
    oldLines: number;
    newStart: number;
    newLines: number;
    lines: string[];
  }>;
  originalFile: string | null;
  gitDiff?: {
    filename: string;
    status: "modified" | "added";
    additions: number;
    deletions: number;
    changes: number;
    patch: string;
    repository?: string | null;
  };
  userModified?: boolean;
};

מחזיר את תוצאת הכתיבה עם מידע diff מובנה. מה ש-originalFile ו-structuredPatch מכילים תלוי בכתיבה:

• עבור קובץ שנוצר זה עתה, originalFile הוא null ו-structuredPatch ריק
• בדריסה, originalFile נושא את התוכן הקודם, למעט כאשר תוכן זה גדול מכ-10 MB: Claude Code אז מדלג על ה-diff ומחזיר originalFile כ-null ו-structuredPatch ריק
• structuredPatch ריק גם כאשר הכתיבה לא שינתה דבר או שה-diff הגיע לזמן קצוב

#Glob

שם הכלי: Glob

type GlobOutput = {
  durationMs: number;
  numFiles: number;
  filenames: string[];
  truncated: boolean;
  totalMatches?: number;
  countIsComplete?: boolean;
};

מחזיר נתיבי קבצים התואמים לתבנית ה-glob, ממוינים לפי זמן שינוי.

totalMatches ו-countIsComplete דורשים Claude Code v2.1.191 או חדש יותר. totalMatches מדווח על מספר הקבצים התואמים לפני קיטוע. כאשר countIsComplete הוא false, totalMatches הוא חסם תחתון משום שהחיפוש הבסיסי קיטע את הפלט שלו עצמו.

#Grep

שם הכלי: Grep

type GrepOutput = {
  mode?: "content" | "files_with_matches" | "count";
  numFiles: number;
  filenames: string[];
  content?: string;
  numLines?: number;
  numMatches?: number;
  totalFiles?: number;
  totalLines?: number;
  appliedLimit?: number;
  appliedOffset?: number;
};

מחזיר תוצאות חיפוש. הצורה משתנה לפי mode: רשימת קבצים, תוכן עם התאמות, או ספירות התאמות. במצב count, numFiles ו-numMatches הם סכומים על כל קבוצת התוצאות, לא על הפרוסה לאחר העימוד. לפני v2.1.208, head_limit או offset שקיטעו את הרשומות המוצגות קיטעו גם את הסכומים האלה.

totalFiles דורש Claude Code v2.1.208 או חדש יותר ומדווח על המספר הכולל של התוצאות לפני עימוד head_limit ו-offset במצב files_with_matches. totalLines דורש Claude Code v2.1.210 או חדש יותר ומדווח על המספר הכולל של השורות לפני עימוד במצב content.

#TaskStop

שם הכלי: TaskStop

type TaskStopOutput = {
  message: string;
  task_id: string;
  task_type: string;
  command?: string;
};

מחזיר אישור לאחר עצירת משימת הרקע.

#NotebookEdit

שם הכלי: NotebookEdit

type NotebookEditOutput = {
  new_source: string;
  old_source?: string;
  cell_id?: string;
  cell_type: "code" | "markdown";
  language: string;
  edit_mode: string;
  error?: string;
  notebook_path: string;
  original_file: string;
  updated_file: string;
};

מחזיר את תוצאת עריכת המחברת עם תוכן הקובץ המקורי והמעודכן.

#WebFetch

שם הכלי: WebFetch

type WebFetchOutput = {
  bytes: number;
  code: number;
  codeText: string;
  result: string;
  durationMs: number;
  url: string;
  artifactRead?: {
    slug: string;
    ver?: string;
    seeded?: false;
  };
};

מחזיר את התוכן שנשלף עם סטטוס HTTP ומטא-נתונים.

artifactRead הוא הרשומה של Claude Code עצמו על קריאת artifact, וקיים רק כאשר Claude שלף artifact שהסשן יכול לפרסם אליו. Claude Code קורא אותו בחזרה כאשר סשן מתחדש כך שפרסום מאוחר יותר נבנה על הגרסה הנכונה. הקוד שלכם לא צריך לפעול עליו. slug נותן שם ל-artifact, ver הוא הגרסה שהקריאה רשמה וחסר כאשר לא נרשמה אף אחת, ו-seeded: false מסמן קריאה שהמקור המלא שלה לא הגיע ל-Claude. השדה seeded דורש Agent SDK v0.3.239 או חדש יותר.

#WebSearch

שם הכלי: WebSearch

type WebSearchOutput = {
  query: string;
  results: Array<
    | {
        tool_use_id: string;
        content: Array<{ title: string; url: string }>;
      }
    | string
  >;
  durationSeconds: number;
  searchCount?: number;
};

מחזיר תוצאות חיפוש מהאינטרנט.

#Workflow

שם הכלי: Workflow

type WorkflowOutput = {
  status: "async_launched" | "remote_launched";
  taskId: string;
  taskType?: "local_workflow" | "remote_agent";
  workflowName?: string;
  runId?: string;
  summary?: string;
  transcriptDir?: string;
  scriptPath?: string;
  sessionUrl?: string; // set when the workflow launched as a cloud session
  warning?: string;
  error?: string;
};

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

#TodoWrite

שם הכלי: TodoWrite

type TodoWriteOutput = {
  oldTodos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
  newTodos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
};

מחזיר את רשימות המשימות הקודמת והמעודכנת.

[!NOTE]

הכלים הבאים זמינים כברירת מחדל רק ב-Claude Opus 4.7, Claude Sonnet 4.6, Claude Haiku 4.5, ובמודלים מוקדמים יותר. בכל מודל אחר, כולל מזהי מודל ש-Claude Code לא מזהה, הם אינם זמינים אלא אם כן בוחרים להפעיל אותם:

• TodoWrite
• TaskCreate
• TaskGet
• TaskUpdate
• TaskList

בכל מקום שבו הכלים זמינים, Claude Code מספק את ארבעת כלי ה-Task, או את TodoWrite במקומם כאשר מגדירים CLAUDE_CODE_ENABLE_TASKS=0.

קבוצת ברירת המחדל הזו חלה ב-Claude Code v2.1.268 ואילך, ש-TypeScript Agent SDK אורז החל מ-v0.3.268.

ראו זמינות מודל כדי להפעיל.

#TaskCreate

שם הכלי: TaskCreate

type TaskCreateOutput = {
  task: {
    id: string;
    subject: string;
  };
};

מחזיר את המשימה שנוצרה עם המזהה שהוקצה לה.

#TaskUpdate

שם הכלי: TaskUpdate

type TaskUpdateOutput = {
  success: boolean;
  taskId: string;
  updatedFields: string[];
  error?: string;
  statusChange?: {
    from: string;
    to: string;
  };
};

מחזיר את תוצאת העדכון, כולל אילו שדות השתנו.

#TaskGet

שם הכלי: TaskGet

type TaskGetOutput = {
  task: {
    id: string;
    subject: string;
    description: string;
    status: "pending" | "in_progress" | "completed";
    blocks: string[];
    blockedBy: string[];
  } | null;
};

מחזיר את רשומת המשימה המלאה, או null כאשר המזהה לא נמצא.

#TaskList

שם הכלי: TaskList

type TaskListOutput = {
  tasks: Array<{
    id: string;
    subject: string;
    status: "pending" | "in_progress" | "completed";
    owner?: string;
    blockedBy: string[];
  }>;
};

מחזיר תמונת מצב של כל המשימות ברשימה הנוכחית.

#ExitPlanMode

שם הכלי: ExitPlanMode

type ExitPlanModeOutput = {
  plan: string | null;
  isAgent: boolean;
  filePath?: string;
  hasTaskTool?: boolean;
  planWasEdited?: boolean;
  awaitingLeaderApproval?: boolean;
  requestId?: string;
};

מחזיר את מצב התוכנית לאחר יציאה ממצב תוכנית.

#ListMcpResources

שם הכלי: ListMcpResourcesTool

type ListMcpResourcesOutput = Array<{
  uri: string;
  name: string;
  mimeType?: string;
  description?: string;
  server: string;
}>;

מחזיר מערך של משאבי MCP זמינים.

#ReadMcpResource

שם הכלי: ReadMcpResourceTool

type ReadMcpResourceOutput = {
  contents: Array<{
    uri: string;
    mimeType?: string;
    text?: string;
    blobSavedTo?: string;
  }>;
  error?: string;
};

מחזיר את התוכן של משאב ה-MCP המבוקש.

#EnterWorktree

שם הכלי: EnterWorktree

type EnterWorktreeOutput = {
  worktreePath: string;
  worktreeBranch?: string;
  message: string;
};

מחזיר מידע על ה-git worktree.

#ExitWorktree

שם הכלי: ExitWorktree

type ExitWorktreeOutput = {
  action: "keep" | "remove";
  originalCwd: string;
  worktreePath: string;
  worktreeBranch?: string;
  tmuxSessionName?: string;
  discardedFiles?: number;
  discardedCommits?: number;
  message: string;
};

מחזיר את הפעולה שבוצעה ופרטים על ה-worktree שממנו יצאו.

#EnterPlanMode

שם הכלי: EnterPlanMode

type EnterPlanModeOutput = {
  message: string;
};

מחזיר אישור שמצב תוכנית הופעל.

#CronCreate

שם הכלי: CronCreate

type CronCreateOutput = {
  id: string;
  humanSchedule: string;
  recurring: boolean;
  durable?: boolean; // true when persisted to .claude/scheduled_tasks.json; false when session-only
  nextFireAt?: number;
};

מחזיר את מזהה העבודה, לוח זמנים קריא לאדם, ואת זמן הריצה הבא. nextFireAt נותן אותו באלפיות שנייה של epoch, כאשר jitter כבר הוחל, כך שזה הזמן שבו העבודה מוגדרת לרוץ. השדה דורש TypeScript Agent SDK v0.3.299 או חדש יותר ו-Claude Code v2.1.299 או חדש יותר.

#CronDelete

שם הכלי: CronDelete

type CronDeleteOutput = {
  id: string;
};

מחזיר את המזהה של העבודה שנמחקה.

#CronList

שם הכלי: CronList

type CronListOutput = {
  jobs: {
    id: string;
    cron: string;
    humanSchedule: string;
    prompt: string;
    recurring?: boolean;
    durable?: boolean;
    nextFireAt?: number;
  }[];
};

מחזיר את עבודות ה-cron המתוזמנות: עבודות durable מ-.claude/scheduled_tasks.json ועבודות של הסשן בלבד מהסשן הנוכחי. עבודה של הסשן בלבד נושאת durable: false. עבודות שנקראו מהדיסק משמיטות את השדה.

nextFireAt הוא זמן הריצה הבא של העבודה באלפיות שנייה של epoch, כולל jitter. אין ערך מוקדם יותר מקריאת CronList: עבודה שהזמן שלה חלף בלי ריצה נושאת את זמן הקריאה. השדה דורש TypeScript Agent SDK v0.3.299 או חדש יותר ו-Claude Code v2.1.299 או חדש יותר.

#ScheduleWakeup

שם הכלי: ScheduleWakeup

type ScheduleWakeupOutput = {
  scheduledFor: number;
  clampedDelaySeconds: number;
  wasClamped: boolean;
  stopped?: boolean;
  cancelledWakeups?: number;
};

מחזיר מתי ההתעוררות תתרחש כחותמת זמן של epoch באלפיות השנייה, את ההשהיה שבה נעשה שימוש בפועל, והאם ההשהיה המבוקשת נחתכה. השדה stopped הוא true כשהקריאה סיימה את הלולאה עם stop: true. זה דורש Claude Code v2.1.202 או חדש יותר. השדה cancelledWakeups סופר כמה התעוררויות ממתינות קריאה עם stop: true ביטלה. ערך 0 אומר ששום דבר לא היה ממתין, ו-cron חוזר של /loop לא מבוטל על ידי stop: true. זה דורש Claude Code v2.1.206 או חדש יותר.

#RemoteTrigger

שם הכלי: RemoteTrigger

type RemoteTriggerOutput = {
  status: number;
  json: string;
  summary?: string;
};

מחזיר את סטטוס התגובה של ה-API ואת הגוף עבור פעולת ה-trigger.

#PushNotification

שם הכלי: PushNotification

type PushNotificationOutput = {
  message: string;
  pushSent?: boolean;
  localSent?: boolean;
  disabledReason?: "config_off" | "user_present" | "no_transport";
  sentAt?: string;
};

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

#ReportFindings

שם הכלי: ReportFindings

type ReportFindingsOutput = {
  count: number;
  level?: "low" | "medium" | "high" | "xhigh" | "max";
  findings: Array<{
    file: string;
    line?: number;
    summary: string;
    failure_scenario: string;
    short_summary?: string;
    category?: string;
    verdict?: "CONFIRMED" | "PLAUSIBLE";
    outcome?: "fixed" | "skipped" | "no_change_needed";
  }>;
};

מחזיר את מספר הממצאים שדווחו, את ערך level ש-Claude העביר, ואת הממצאים שהוחזרו בגוף התוצאה. דורש Claude Code v2.1.196 או חדש יותר. השדה short_summary המוחזר דורש Claude Code v2.1.212 או חדש יותר.

#Artifact

שם הכלי: Artifact

type ArtifactOutput =
  | {
      url: string;
      path: string;
      title?: string;
      version?: string;
      capabilities?: unknown;
      stored?: {
        contract: string;
        capabilities?: Record<string, unknown>;
      };
      warnings?: string[];
      contract?: string;
      updated?: boolean;
      liveSubscription?: string;
    }
  | {
      artifacts: Array<{
        title: string;
        url: string;
        updatedAt?: string;
        rel?: "mine" | "shared";
      }>;
      truncated?: boolean;
      total?: number;
      total_at_least?: true;
      scope?: "shared" | "all";
    };

מחזיר את url של הדף שפורסם ואת path המקומי שפורסם עבור פעולת הפרסום, עם updated מוגדר ל-true כשהפרסום פרס מחדש artifact קיים, ו-warnings נושא כל הודעות ייעוץ מזמן הפרסום. פעולת הרשימה מחזירה במקום זאת את שורות artifacts, עם truncated מוגדר כשקיימים יותר artifacts מהמגבלה המבוקשת. ברשימות שה-scope שלהן אינו "mine", כל שורה נושאת rel שמסמן אם המשתמש הוא הבעלים של ה-artifact או שהוא שותף איתו, וה-scope של הפלט מתעד איזה scope שאינו ברירת המחדל יצר את הרשימה. שניהם נעדרים ברשימות ברירת המחדל.

תוצאת רשימה מדווחת גם על total, מספר ה-artifacts שתואמים ל-scope שברשימה, כולל אלה שמעבר ל-limit. כש-total_at_least מוגדר, המספר הזה הוא גבול תחתון וייתכן שקיימים artifacts נוספים. שני השדות דורשים Agent SDK v0.3.292 או חדש יותר.

#Projects

שם הכלי: Projects

type ProjectsOutput =
  | {
      method: "project_info";
      notice?: string;
      name: string;
      description: string;
      instructions: string;
      docs: Array<{ path: string; created_at: string | null }>;
      files?: Array<{
        path: string;
        file_kind: string;
        created_at: string | null;
      }>;
      sync_sources?: Array<{
        type: string | null;
        config: Record<string, unknown>;
      }>;
      knowledge: {
        knowledge_size: number;
        max_knowledge_size: number;
      };
    }
  | {
      method: "project_read";
      notice?: string;
      path: string;
      file_kind?: string;
      content?: string;
      local_file?: string;
      created_at: string | null;
    }
  | {
      method: "project_search";
      notice?: string;
      rag: boolean;
      hits?: Array<{ name?: string; doc_uuid?: string; text?: string }>;
      docs?: string[];
    }
  | {
      method: "project_write";
      notice?: string;
      path: string;
      doc_uuid: string;
      replaced: boolean;
      present_to_user?: boolean;
      local_path?: string;
    }
  | {
      method: "project_delete";
      notice?: string;
      path: string;
      deleted: boolean;
    };

מובחן לפי השדה method, בדומה לקלט. project_read מחזיר מסמכי טקסט קטנים בתוך content וכותב מסמכים גדולים יותר לנתיב local_file במקום זאת. project_search מחזיר hits של RAG עם rag: true כשהאינדקס של הפרויקט זמין, ונופל חזרה לרשימת נתיבי docs אחרת.

#ReadMcpResourceDir

שם הכלי: ReadMcpResourceDirTool

type ReadMcpResourceDirOutput = {
  resources: Array<{
    uri: string;
    name: string;
    mimeType?: string;
  }>;
  error?: string;
};

מחזיר את הילדים הישירים של משאב הספרייה. ספריות משנה מופיעות עם mimeType "inode/directory". error נושא הודעה קריאה לאדם כשהשרת לא הצליח לרשום את הספרייה.

#RefreshMcpTools

שם הכלי: RefreshMcpTools

type RefreshMcpToolsOutput = Array<{
  server: string;
  status: "refreshed" | "error" | "not_connected";
  toolCount?: number; // tools now available from this server
  added?: string[]; // tool names this refresh added
  removed?: string[]; // tool names this refresh removed
  error?: string; // why the refresh failed or the server was unavailable
}>;

מחזיר רשומה אחת לכל שרת: refreshed אומר שרשימת הכלים שנשאלה מחדש הוחלה, error אומר שהשאילתה מחדש נכשלה וסט הכלים הקודם נשמר, ו-not_connected אומר שלשרת אין חיבור חי לשאילתה.

#ShowOnboardingRolePicker

שם הכלי: ShowOnboardingRolePicker

type ShowOnboardingRolePickerOutput = {
  role?: string;
  dismissed?: boolean;
};

מחזיר את בחירת המשתמש: role כשהוא בחר שבב תפקיד או הקליד אחד, ו-dismissed: true כשהוא סגר את הבורר. אובייקט ריק אומר שהמשתמש אישר את הקריאה בלי לבחור תפקיד.

#McpOutput

שם הכלי: שמות כלי MCP דינמיים בצורה mcp__<server>__<tool>

type McpOutput =
  | string
  | {
      type: string;
      [k: string]: unknown;
    }[]
  | {
      [k: string]: unknown;
    };

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

#טיפוסי הרשאה

#PermissionUpdate

פעולות לעדכון הרשאות.

type PermissionUpdate =
  | {
      type: "addRules";
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: "replaceRules";
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: "removeRules";
      rules: PermissionRuleValue[];
      behavior: PermissionBehavior;
      destination: PermissionUpdateDestination;
    }
  | {
      type: "setMode";
      mode: PermissionMode;
      destination: PermissionUpdateDestination;
    }
  | {
      type: "addDirectories";
      directories: string[];
      destination: PermissionUpdateDestination;
    }
  | {
      type: "removeDirectories";
      directories: string[];
      destination: PermissionUpdateDestination;
    };

#PermissionBehavior

type PermissionBehavior = "allow" | "deny" | "ask";

#PermissionUpdateDestination

type PermissionUpdateDestination =
  | "userSettings" // Global user settings
  | "projectSettings" // Per-directory project settings
  | "localSettings" // Local project settings
  | "session" // Current session only
  | "cliArg"; // CLI argument

#PermissionRuleValue

type PermissionRuleValue = {
  toolName: string;
  ruleContent?: string;
};

#טיפוסים אחרים

#ApiKeySource

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

type ApiKeySource =
  | "ANTHROPIC_API_KEY"
  | "apiKeyHelper"
  | "/login managed key"
  | "none"
  | "user"
  | "project"
  | "org"
  | "temporary"
  | "oauth";

Claude Code מדווח על אחד מארבעה ערכים:

Agent SDK v0.3.234 וחדש יותר מציינים את ארבעת הערכים האלה בטיפוס. הטיפוס שומר גם את user, project, org, temporary ו-oauth כדי שקוד ישן יותר עדיין יתקמפל, ו-Claude Code לא מדווח עליהם.

#SdkBeta

תכונות בטא זמינות שאפשר להפעיל דרך האפשרות betas. ראה Beta headers למידע נוסף.

type SdkBeta = "context-1m-2025-08-07";

[!WARNING]

ב-Claude API, הבטא context-1m-2025-08-07 יצאה משימוש עבור Claude Sonnet 4.5 ו-Claude Sonnet 4. אם עדיין מעבירים אותה עם אחד מהמודלים האלה, בקשות שחורגות מחלון ההקשר הסטנדרטי של 200K טוקנים מחזירות שגיאה, אז הסר אותה מ-betas. כדי להריץ סשן עם חלון הקשר של 1M טוקנים, הגדר את model למודל שרץ עם חלון 1M כברירת מחדל, כמו claude-sonnet-5-5 או claude-opus-5-5. עבור מודל שמגיע ל-1M רק דרך וריאנט [1m] שלו, הוסף את הסיומת למזהה המודל, כמו ב-claude-opus-4-6[1m].

#SlashCommand

מידע על פקודה זמינה.

type SlashCommand = {
  name: string;
  description: string;
  argumentHint: string;
  aliases?: string[];
  builtin?: boolean;
};

builtin הוא true בשורה כשהפקודה היא של Claude Code עצמו והקלדת /name מריצה אותה. הוא נעדר עבור פקודה שהוגדרה על ידי משתמש, פרויקט, תוסף, או שרת MCP, ועבור פקודה ארוזה שאחד מאלה מחליף לפי שם. דורש Agent SDK v0.3.277 או חדש יותר.

#ModelInfo

מידע על מודל זמין.

type ModelInfo = {
  value: string;
  resolvedModel?: string;
  displayName: string;
  description: string;
  supportsEffort?: boolean;
  supportedEffortLevels?: ("low" | "medium" | "high" | "xhigh" | "max")[];
  supportsAdaptiveThinking?: boolean;
  supportsFastMode?: boolean;
  supportsAutoMode?: boolean;
};

#AgentInfo

מידע על סוכן משנה זמין שאפשר להפעיל דרך הכלי Agent.

type AgentInfo = {
  name: string;
  description: string;
  model?: string;
};

#McpServerProvenance

שרת ה-MCP שמגיש כלי mcp__*, ומאיפה הגיעה ההגדרה של השרת הזה. קלטי ה-hook PreToolUse, PostToolUse, PostToolUseFailure, PermissionRequest ו-PermissionDenied נושאים אותו כ-mcp_server, והאפשרויות של CanUseTool נושאות אותו כ-mcpServer. שניהם משמיטים אותו עבור כלים שלא מגיעים משרת MCP.

type McpServerProvenance = {
  name: string;
  source: string;
};

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

• sdk: שרת בתוך התהליך שהאפליקציה שלך רשמה. רק אפליקציית המארח של ה-SDK יכולה לרשום אחד, אז שרת מוגדר לעולם לא מדווח sdk, יהיה שמו אשר יהיה.
• plugin: שרת שתוסף מספק. ה-name שלו הוא הצורה המתוחמת plugin:<plugin-name>:<server-name> המתוארת תחת שרתי MCP שמסופקים על ידי תוסף.
• scope של תצורה: user, project, local, dynamic, managed, enterprise, claudeai, או agent. שרת .mcp.json מדווח project, ו-היקפי התקנת MCP מגדיר את local, project ו-user. שרתים שהאפליקציה שלך מעבירה באפשרות mcpServers, מלבד שרתי SDK בתוך התהליך, מדווחים dynamic.

בסס החלטות אמון על source, לא על name או על קידומת שם הכלי mcp__<server>__. עבור כל מקור שאינו sdk, name הוא טקסט לא מהימן: בצע לו escape לפני תצוגה.

McpServerProvenance והשדות שנושאים אותו דורשים Agent SDK v0.3.274 או חדש יותר.

#McpServerStatus

הסטטוס של שרת MCP מחובר.

type McpServerStatus = {
  name: string;
  status: "connected" | "failed" | "needs-auth" | "pending" | "disabled";
  serverInfo?: {
    name: string;
    version: string;
  };
  error?: string;
  config?: McpServerStatusConfig;
  scope?: string;
  source?: string;
  tools?: {
    name: string;
    description?: string;
    annotations?: {
      readOnly?: boolean;
      destructive?: boolean;
      openWorld?: boolean;
    };
    _meta?: Record<string, unknown>;
  }[];
};

השתמש ב-source כדי להחליט עד כמה לסמוך על שרת, וב-_meta בכל רשומת tools כדי למצוא משאב UI שהשרת צירף לכלי הזה:

• source: המקור שממנו הגיעה הגדרת השרת, עם אותם ערכים כמו source ב-McpServerProvenance. בסס החלטות אמון על source ולא על name, כי רק השרת שלך בתוך התהליך מדווח sdk, בלי קשר לשם שבו נרשם כל שרת אחר. אם אינך מזהה ערך source, התייחס לשרת הזה כמו לכל שרת ש-source שלו אינו sdk. דורש Agent SDK v0.3.274 או חדש יותר
• _meta: אובייקט ui ומחרוזת ui/resourceUri מתוך _meta שהשרת הצהיר עבור הכלי. Claude Code מונע כל מפתח _meta אחר. ui/resourceUri הוא איות ישן ברמה העליונה של ui.resourceUri. כשהשרת מצרף משאב MCP Apps UI לכלי, ui.resourceUri או ui/resourceUri מחזיקים את ה-URI מסוג ui:// של המשאב. שלוף את ה-URI הזה עם readMcpResource() והצג את המשאב ביישום שלך. דורש Agent SDK v0.3.280 או חדש יותר

Claude Code שולח _meta רק כשמערך capabilities של הודעת system עם subtype init מציין mcp_tool_ui_meta_v1. אינך מפעיל את mcp_tool_ui_meta_v1 בעצמך.

#כש-_meta.ui של כלי מחזיק רק visibility

אם השרת שלך מצהיר ui.resourceUri עבור כלי, אבל _meta.ui שהיישום שלך מקבל מחזיק רק visibility, אובייקט ui שהשרת שלח נכשל באחת הבדיקות של Claude Code. השווה את _meta בתשובת tools/list של השרת שלך מול הבדיקות של כל מפתח:

• ui: מגיע ליישום שלך ללא שינוי, כולל כל חברים שאינם resourceUri ו-visibility, אם כל שלוש הבדיקות עוברות:

  • resourceUri נעדר, או שהוא מחרוזת שמתחילה ב-ui://
  • visibility נעדר, או שהוא מציין רק "model" ו-"app"
  • האובייקט כולו הוא לכל היותר 4,096 תווים כשהוא מסודר כ-JSON

  אם אחת מהבדיקות נכשלת, היישום שלך מקבל לכל היותר ui שהחבר היחיד שלו הוא מערך visibility עם רשומות "model" ו-"app" שהשרת ציין.

• ui/resourceUri: מגיע ליישום שלך אם הוא מחרוזת שמתחילה ב-ui:// ואורכה לכל היותר 4,096 תווים. אחרת Claude Code משמיט אותו

כש-Claude Code נשאר בלי חבר ui ובלי מחרוזת ui/resourceUri לשליחה, לרשומת tools אין _meta כלל.

#McpServerStatusConfig

התצורה של שרת MCP כפי שמדווח mcpServerStatus(). זה האיחוד של כל סוגי התעבורה של שרתי MCP.

type McpServerStatusConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfig
  | McpClaudeAIProxyServerConfig;

ראה McpServerConfig לפרטים על כל סוג תעבורה.

#AccountInfo

מידע חשבון של המשתמש המאומת.

type AccountInfo = {
  email?: string;
  organization?: string;
  subscriptionType?: string;
  tokenSource?: string;
  apiKeySource?: string;
};

#ModelUsage

סטטיסטיקת שימוש לפי מודל שמוחזרת בהודעות תוצאה. הערך costUSD הוא אומדן בצד הלקוח. ראה Track cost and usage להסתייגויות חיוב.

type ModelUsage = {
  inputTokens: number;
  outputTokens: number;
  thinkingTokens?: number;
  cacheReadInputTokens: number;
  cacheCreationInputTokens: number;
  webSearchRequests: number;
  costUSD: number;
  contextWindow: number;
  maxOutputTokens: number;
  canonicalModel?: string;
  provider?: string;
  costBasis?: 'list' | 'managed' | 'unknown';
};

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

השדות canonicalModel ו-provider דורשים Claude Code v2.1.218 או חדש יותר. canonicalModel הוא מזהה המודל הקנוני שבו משתמש חיפוש התמחור. הוא יכול להיות שונה ממחרוזת המודל הגולמית שמשמשת מפתח לרשומה, למשל כשהמחרוזת הזו היא מזהה ייחודי לספק או כינוי.

provider מציין את קצה ה-API ששירת את המודל, כגון firstParty, bedrock, vertex, foundry, anthropicAws, mantle, או gateway.

costBasis מציין את טבלת המחירים שתימחרה את הבקשה האחרונה של המודל: list למחיר מחירון, managed לטבלת modelPricing, או unknown כשאף אחת מהן לא התאימה למזהה המודל. השדה דורש Claude Code v2.1.246 או חדש יותר.

#ConfigScope

type ConfigScope = "local" | "user" | "project";

#NonNullableUsage

גרסה של Usage שבה כל שדה שניתן ל-null הפך ללא ניתן ל-null, חוץ מ-fallback_credit, שעדיין יכול להיות null.

type NonNullableUsage = {
  [K in keyof Usage]: K extends "fallback_credit"
    ? Usage[K]
    : NonNullable<Usage[K]>;
};

#Usage

סטטיסטיקת שימוש בטוקנים. זה הטיפוס BetaUsage מ-@anthropic-ai/sdk.

type Usage = {
  input_tokens: number;
  output_tokens: number;
  cache_creation_input_tokens: number | null;
  cache_read_input_tokens: number | null;
  cache_creation: {
    ephemeral_5m_input_tokens: number;
    ephemeral_1h_input_tokens: number;
  } | null;
  server_tool_use: BetaServerToolUsage | null;
  service_tier: "standard" | "priority" | "batch" | null;
  speed: "standard" | "fast" | null;
  inference_geo: string | null;
  iterations: BetaIterationsUsage | null;
  output_tokens_details: BetaOutputTokensDetails | null;
  fallback_credit: BetaFallbackCreditUsage | null;
};

BetaServerToolUsage, BetaIterationsUsage, BetaOutputTokensDetails, ו-BetaFallbackCreditUsage מוגדרים ב-@anthropic-ai/sdk.

output_tokens_details מפרק את הפלט המחויב לפי קטגוריה. כרגע הוא נושא שדה אחד, thinking_tokens: number, שסופר את טוקני הפלט שהמודל יצר כהיגיון פנימי, כולל תוחמי בלוק החשיבה. השדה output_tokens_details דורש TypeScript SDK v0.3.228 או חדש יותר, שכולל את Claude Code v2.1.228.

• חיוב: קרא את הפירוט לצורך תצפית, לא לצורך חיוב. output_tokens נשאר הסכום הסמכותי, ו-output_tokens - thinking_tokens מקרב את הפלט שאינו היגיון.
• מה הספירה מכסה: ההיגיון הגולמי שהמודל ייצר, שיכול להיות ארוך יותר מטקסט החשיבה שמוחזר בגוף התשובה. ה-API מחשב אותו על ידי טוקניזציה מחדש של הטקסט הגולמי הזה, כך שהוא יכול להיות שונה מספירת היצירה המדויקת של המודל בכמה טוקנים.
• הזרמה: בהודעות assistant מוזרמות הפירוט הזה, כמו output_tokens, הוא ממלא מקום של message_start ואינו נושא ספירה אמיתית, לכן קרא אותו מ-usage של הודעת התוצאה כפי שמתאר Read output tokens from the result message. בהודעת התוצאה, thinking_tokens נקרא 0 כשהמודל או הספק מדווחים שאין פירוט.
• מקרי null: output_tokens_details עצמו הוא null בהודעות assistant ש-Claude Code מסנתז, כגון הודעות שגיאת API.

האם Usage נושא fallback_credit תלוי ב-@anthropic-ai/sdk המותקן אצלך, שהוסיף אותו ב-0.115.0.

#CallToolResult

טיפוס תוצאת כלי MCP (מ-@modelcontextprotocol/sdk/types.js). structuredContent הוא אובייקט JSON שאפשר להחזיר לצד content, כולל בלוקי תמונה. ראה Return structured data.

type CallToolResult = {
  content: Array<{
    type: "text" | "image" | "audio" | "resource" | "resource_link";
    // Additional fields vary by type
  }>;
  structuredContent?: Record<string, unknown>;
  isError?: boolean;
};

#SDKMcpResourceLink

קובץ אחד שכלי MCP החזיר לפי הפניה. Claude Code בונה כל רשומה מבלוק resource_link בתוצאת הכלי ומעביר את הרשימה כ-resourceLinks ב-SDKUserMessage.tool_use_result, או כ-resource_links ב-SDKTaskNotificationMessage כשהקריאה הסתיימה ברקע. דורש Agent SDK v0.3.257 או חדש יותר.

type SDKMcpResourceLink = {
  uri: string;
  name: string;
  title?: string;
  description?: string;
  mimeType?: string;
  size?: number;
  annotations?: Record<string, unknown>;
};

Claude Code משמיט בלוק ש-uri או name שלו אינו מחרוזת, ומשמיט שדה אופציונלי שהערך שלו אינו מהטיפוס המפורט.

#ThinkingConfig

שולט בהתנהגות החשיבה או ההיגיון של Claude. מקבל עדיפות על פני maxThinkingTokens שיצא משימוש.

type ThinkingDisplay = "summarized" | "omitted";

type ThinkingConfig =
  | { type: "adaptive"; display?: ThinkingDisplay } // The model determines when and how much to reason (Opus 4.6+)
  | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // Fixed thinking token budget
  | { type: "disabled" }; // No extended thinking

השדה האופציונלי display קובע אם טקסט החשיבה מוחזר "summarized" או "omitted". ב-Claude Opus 4.7 ואילך, ברירת המחדל של ה-API היא "omitted", לכן קבע "summarized" כדי לקבל תוכן חשיבה בבלוקי thinking. Claude Code אינו מעביר את ערך display שלך לחלק מהספקים, כגון Amazon Bedrock ו-Agent Platform של Google Cloud. אצל הספקים האלה, Opus 4.7 ואילך מחזירים בלוקי thinking ריקים גם כשאתה קובע display ל-"summarized".

#SpawnedProcess

ממשק ליצירת תהליך מותאם (בשימוש עם האפשרות spawnClaudeCodeProcess). ChildProcess כבר ממלא את הממשק הזה.

interface SpawnedProcess {
  stdin: Writable;
  stdout: Readable;
  readonly killed: boolean;
  readonly exitCode: number | null;
  kill(signal: NodeJS.Signals): boolean;
  on(
    event: "exit",
    listener: (code: number | null, signal: NodeJS.Signals | null) => void
  ): void;
  on(event: "error", listener: (error: Error) => void): void;
  once(
    event: "exit",
    listener: (code: number | null, signal: NodeJS.Signals | null) => void
  ): void;
  once(event: "error", listener: (error: Error) => void): void;
  off(
    event: "exit",
    listener: (code: number | null, signal: NodeJS.Signals | null) => void
  ): void;
  off(event: "error", listener: (error: Error) => void): void;
}

#SpawnOptions

אפשרויות שמועברות לפונקציית ה-spawn המותאמת.

interface SpawnOptions {
  command: string;
  args: string[];
  cwd?: string;
  env: Record<string, string | undefined>;
  signal: AbortSignal;
}

[!NOTE]

השדה signal אומר לפונקציית ה-spawn שלך מתי לפרק את התהליך. העבר אותו כאפשרות signal ל-spawn() של Node, או העבר אותו למטפל הפירוק של ה-VM או הקונטיינר שלך.

האות הזה אינו נורה ברגע ש-Options.abortController מבטל. ה-SDK קודם סוגר את stdin של התהליך וממתין כשתי שניות כדי שה-CLI יוכל להיסגר בצורה נקייה, ואז מבטל את האות הזה. כדי להגיב ברגע שהקורא מבטל, האזן ל-Options.abortController.signal שלך, שפונקציית ה-spawn שלך יכולה להפנות אליו מההיקף הסוגר שלה.

#McpSetServersResult

תוצאה של פעולת setMcpServers().

type McpSetServersResult = {
  added: string[];
  removed: string[];
  errors: Record<string, string>;
};

ההבטחה של setMcpServers() נפתרת אחרי ששרתי stdio, HTTP ו-SSE שנוספו לאחרונה מתחברים או נכשלים, כך שכלים משרתים שהתחברו זמינים בתור הבא.

כשאתה קורא ל-setMcpServers(), Claude Code מיישם את הכללים האלה:

• שרתים שהקריאה אינה מציינת: מחוץ ל-סשן ענן, Claude Code מנתק את השרתים שקריאת setMcpServers() קודמת הוסיפה ואת שרתי ה-SDK בתוך התהליך, ומציין אותם ב-removed. שרתים אחרים ממשיכים לרוץ ואינם מצוינים ב-removed, וביניהם שרתי stdio, HTTP ו-SSE מאפשרות mcpServers, שרתים מקובצי הגדרות, ושרתים שתוסף סיפק.
• שרתי stdio, HTTP ו-SSE שקריאת setMcpServers() קודמת הוסיפה: מחוץ לסשן ענן, שרת שאתה מציין שוב עם תצורה זהה שומר את החיבור והכלים שלו. הוא אינו מופיע ב-added ואינו מופיע ב-removed. אם אתה מעביר תצורה שהשתנתה, Claude Code מתחבר מחדש לשרת באמצעות התצורה הזו ומציין אותו ב-added, לא ב-removed.
• שרתי stdio, HTTP ו-SSE שהקריאה מציינת וששום קריאה קודמת לא הוסיפה: מחוץ לסשן ענן, Claude Code מוסיף את השרת ומציין אותו ב-added, או ב-errors אם הוא מסרב לשרת.
• שרתי SDK בתוך התהליך שהקריאה מציינת: שרת שכבר נרשם דרך mcpServers או קריאה קודמת שומר את המופע הרץ ואת ה-timeout שלו. אם אתה מעביר עבורו רשימת מדיניות tools, גם ריקה, אתה מחליף את המדיניות שלו. אחרת הן נשארות. כדי להריץ מופע חדש מחוץ לסשן ענן, השמט את השרת מקריאה אחת וציין אותו בקריאה הבאה.
• שרתים מובנים שה-CLI הפעיל בהפעלה: אם הקריאה מציינת אחד, Claude Code משמיט את הרשומה הזו ומדווח אותה ב-errors.
• שרתי stdio, HTTP או SSE שחולקים שם עם שרת מהיקף התקנת MCP כגון .mcp.json: תחת השם הזה הסשן משתמש בכלים של השרת שלך ולא בשרת מהיקף ההתקנה. לפני Claude Code v2.1.305, Claude Code יכול היה לנתק את השרת שלך ולחבר את שרת היקף ההתקנה כשהיישום שלך טען מחדש תוספים.

added מציין את השרתים ש-Claude Code הוסיף או החליף, בין שהתחברו ובין שלא. שרת שנכשל בחיבור מופיע גם ב-added וגם ב-errors, עם טקסט הכשל תחת errors ושורה failed ב-mcpServerStatus(). לפני Claude Code v2.1.257, שרת שניסיון החיבור שלו זרק דווח רק תחת errors.

ערך errors שמתחיל ב-Blocked by enterprise אומר שמדיניות סירבה לשרת, לא שהחיבור נכשל:

• Blocked by enterprise policy (allowedMcpServers/deniedMcpServers): השרת אינו ב-added. רשומת deniedMcpServers מתאימה לו, או שרשימת allowedMcpServers מוגדרת ומשמיטה אותו. אם הרשימה הזו נמצאת בקובץ הגדרות שאתה טוען דרך settingSources, ערוך את הקובץ. אם היא נמצאת בהגדרות מנוהלות, בקש מהמנהלים שלך לשנות אותה.
• Blocked by enterprise managed policy: השרת נמצא ב-added, עם שורה failed ב-mcpServerStatus(). בקש ממנהל איזו מדיניות חוסמת אותו.

#RewindFilesResult

תוצאה של פעולת rewindFiles().

type RewindFilesResult = {
  canRewind: boolean;
  error?: string;
  filesChanged?: string[];
  insertions?: number;
  deletions?: number;
  skippedLinks?: number;
};

skippedLinks סופר את הנתיבים המנוטרים שה-rewind סירב לשחזר או למחוק לשם בטיחות קישורים: symlink, hard link, או קובץ לא רגיל אחר בנתיב המנוטר, תיקיית אב שאינה נפתרת עוד למקום שאליו הצביעה כשנקודת הביקורת נלקחה, או גיבוי שלא ניתן היה לקרוא בבטחה. השדה דורש Claude Code v2.1.216 או חדש יותר. קריאת תצוגה מקדימה עם rewindFiles(userMessageId, { dryRun: true }) לעולם אינה קובעת אותו.

#SDKStatusMessage

הודעת עדכון סטטוס (למשל, compacting).

type SDKStatusMessage = {
  type: "system";
  subtype: "status";
  status: "compacting" | null;
  permissionMode?: PermissionMode;
  uuid: UUID;
  session_id: string;
};

#SDKTaskNotificationMessage

התראה כשמשימה ברקע מסתיימת, נכשלת או נעצרת. משימות ברקע כוללות פקודות Bash עם run_in_background, מעקבי Monitor וסוכני משנה ברקע. לשדות run_id ו-ambient ראה SDKTaskStartedMessage, שמגדיר אותם ואת דרישות הגרסה שלהם.

type SDKTaskNotificationMessage = {
  type: "system";
  subtype: "task_notification";
  task_id: string;
  run_id?: string;
  tool_use_id?: string;
  status: "completed" | "failed" | "stopped";
  reason?: "worker_restart";
  output_file: string;
  summary: string;
  ambient?: boolean;
  usage?: {
    total_tokens: number;
    tool_uses: number;
    duration_ms: number;
  };
  resource_links?: SDKMcpResourceLink[];
  uuid: UUID;
  session_id: string;
};

reason מוגדר כשמשימה מסתיימת מסיבה שאינה השלמה, כשל או עצירה משלה, ודורש Agent SDK מגרסה v0.3.273 ואילך. Claude Code מגדיר אותו רק בסשנים שמתחברים דרך claude.ai: סשני ענן, כולל אלה על runners באירוח עצמי, וסשני Remote Control. קריאת query() מקומית אף פעם לא מגדירה אותו. הערך היחיד שלו, worker_restart, אומר שתהליך Claude Code שהריץ את המשימה הופעל מחדש. ההתראה נושאת סטטוס "stopped", לכן יש להתייחס למשימה כאילו לא הושלמה ולא נכשלה.

כש-Claude Code מעביר קריאת כלי MCP ארוכה לרקע, בלוק tool_result של אותה קריאה מחזיק רק ממלא מקום, והתוצאה האמיתית של הקריאה מגיעה בהתראה הזו. התאם את ההתראה לקריאה באמצעות tool_use_id. בהתראת completed, resource_links מפרט את הקבצים שהכלי החזיר לפי הפניה כרשומות SDKMcpResourceLink, עם אותן מגבלות של 50 קישורים ו-64 KiB כמו tool_use_result.resourceLinks. Claude Code משמיט את resource_links כשלתוצאה לא היו קישורים ובהתראות למשימות שאינן קריאות כלי MCP. resource_links דורש Agent SDK מגרסה v0.3.257 ואילך.

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

כדי לזהות תור של התראת משימה, בדוק origin.kind === "task-notification" ב-SDKUserMessage או ב-SDKResultMessage במקום להתאים לטקסט ההודעה. קרא את subkind מאותו שדה אם אתה צריך לדעת מה העלה אותה. לפני v2.1.205, Claude Code השמיט את ההודעה מהתראות שהגיעו בזמן שהסשן היה במצב idle.

#SDKToolUseSummaryMessage

סיכום של שימוש בכלים בשיחה.

type SDKToolUseSummaryMessage = {
  type: "tool_use_summary";
  summary: string;
  preceding_tool_use_ids: string[];
  uuid: UUID;
  session_id: string;
};

#SDKHookStartedMessage

נפלט כש-hook מתחיל לרוץ.

Claude Code מעביר את ההודעה הזו, את SDKHookProgressMessage ואת SDKHookResponseMessage לזרם ההודעות מיד, כולל בזמן ש-hook מסוג SessionStart או Setup עדיין רץ במהלך אתחול הסשן. Claude Code מגרסה v2.1.169 עד v2.1.203 העביר את ההודעות האלה באצווה אחת אחרי ש-hook מסוג SessionStart או Setup הסתיים. v2.1.204 החזיר מסירה חיה.

אם אתה מתחיל את הסשן עם startup(), ההודעות האלה מגיעות אליך אחרי שאתה קורא ל-.query() ועובר על התוצאה.

type SDKHookStartedMessage = {
  type: "system";
  subtype: "hook_started";
  hook_id: string;
  hook_name: string;
  hook_event: string;
  uuid: UUID;
  session_id: string;
};

#SDKHookProgressMessage

נפלט בזמן ש-hook רץ, עם פלט stdout/stderr.

type SDKHookProgressMessage = {
  type: "system";
  subtype: "hook_progress";
  hook_id: string;
  hook_name: string;
  hook_event: string;
  stdout: string;
  stderr: string;
  output: string;
  uuid: UUID;
  session_id: string;
};

#SDKHookResponseMessage

נפלט כש-hook מסיים לרוץ.

type SDKHookResponseMessage = {
  type: "system";
  subtype: "hook_response";
  hook_id: string;
  hook_name: string;
  hook_event: string;
  output: string;
  stdout: string;
  stderr: string;
  exit_code?: number;
  outcome: "success" | "error" | "cancelled";
  uuid: UUID;
  session_id: string;
};

#SDKToolProgressMessage

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

type SDKToolProgressMessage = {
  type: "tool_progress";
  tool_use_id: string;
  tool_name: string;
  parent_tool_use_id: string | null;
  elapsed_time_seconds: number;
  task_id?: string;
  heartbeat?: boolean;
  subagent_type?: string;
  subagent_retry?: {
    agent_id: string;
    attempt: number;
    max_retries: number;
    retry_delay_ms: number;
    error_status: number | null;
    error_category: string;
  };
  uuid: UUID;
  session_id: string;
};

בזמן שקריאת כלי רצה בשיחה הראשית, Claude Code פולט הודעת tool_progress כל 30 שניות עם heartbeat: true. כל heartbeat נושא את שם הכלי ואת השניות שחלפו, כך שאפשר להבדיל בין קריאה ארוכה לבין סשן שנתקע. Claude Code לא פולט heartbeats לקריאות כלי בתוך סוכן משנה. השדה heartbeat דורש Agent SDK מגרסה v0.3.214 ואילך. לפני v2.1.257, Claude Code גם לא פלט heartbeats לקריאת כלי Agent בחזית.

בהודעות tool_progress לכלי Agent שאינן heartbeats, subagent_type מציין את סוג סוכן המשנה שרץ, למשל general-purpose. subagent_retry נוכח בזמן שסוכן המשנה הזה ממתין לנסיגה אחרי שגיאת API, כמו הגבלת קצב או עומס, עם הודעה אחת לכל ניסיון חוזר. שני השדות דורשים Agent SDK מגרסה v0.3.214 ואילך.

כדי להציג מחוון ניסיון חוזר מ-subagent_retry:

• עקוב אחרי המחוון לפי parent_tool_use_id, שהוא ייחודי לכל סוכן משנה. tool_use_id משותף לסוכני משנה מקבילים מתור assistant אחד, ולכן מעקב לפיו יאפשר לעדכון של סוכן משנה אחד לנקות את המחוון של אחר.
• נקה את המחוון כש-tool_progress מאוחר יותר לאותו parent_tool_use_id מגיע בלי subagent_retry ובלי heartbeat: true, או כשמגיעה הודעת התוצאה של הכלי. מסגרות עם heartbeat: true מדווחות רק על חיות, לכן שמור את המחוון כשאחת כזו מגיעה. attempt יכול לעבור את max_retries תחת ניסיון חוזר מתמשך, לכן אל תגזור ניקוי מהמונים.
• התייחס ל-error_category כאסימון לבחירת טקסט הודעה משלך, לא כטקסט תצוגה. הערכים הם rate_limit, overloaded, authentication_failed, server_error, cloud_credential_error ו-unknown. טפל בערך שאינך מזהה כמו שאתה מטפל ב-unknown, כי גרסאות מאוחרות יותר יכולות להוסיף ערכים.

#SDKAuthStatusMessage

נפלט במהלך תהליכי אימות.

type SDKAuthStatusMessage = {
  type: "auth_status";
  isAuthenticating: boolean;
  output: string[];
  error?: string;
  uuid: UUID;
  session_id: string;
};

#SDKTaskStartedMessage

נפלט כשמשימה מתחילה. השדה task_type הוא "local_bash" לפקודות Bash ולמעקבי Monitor, "local_agent" לסוכני משנה, או "remote_agent".

type SDKTaskStartedMessage = {
  type: "system";
  subtype: "task_started";
  task_id: string;
  run_id?: string;
  tool_use_id?: string;
  description: string;
  task_type?: string;
  is_backgrounded?: boolean;
  spawn_depth?: number;
  parent_task_id?: string;
  ambient?: boolean;
  uuid: UUID;
  session_id: string;
};

run_id מזהה ריצה אחת של המשימה. כשמשימה רצה שוב תחת אותו task_id, למשל סוכן משנה ש-Claude ממשיך, הריצה החדשה מקבלת run_id חדש. השדה דורש Agent SDK מגרסה v0.3.292 ואילך. השתמש בו כדי להפריד בין הריצות של משימה אחת:

• התאם הודעות לריצה: הודעות task_started, task_progress, task_updated ו-task_notification של ריצה אחת נושאות את אותו run_id. גם הרשומה של הריצה בכל SDKBackgroundTasksChangedMessage נושאת אותו, וכך גם runId על ה-origin של הודעת המשתמש שמסירה את ההתראה של הריצה.
• זהה הודעה מאוחרת: בהשוואה כמחרוזות רגילות, מזהי הריצה של משימה אחת ממוינים לפי הסדר שבו הריצות התחילו, כך שהודעה ש-run_id שלה ממוין לפני הריצה שאתה מציג מגיעה מריצה קודמת. התייחס לערך כאטום מלבד ההשוואה הזו.
• חזור ל-task_id: כשהודעה לא נושאת run_id, למשל task_notification שסשן שהמשיך פולט כדי לסגור משימה שהתהליך הקודם התחיל, שייך אותה לפי task_id.

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

{"subtype": "task_started", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubbs7i8-6f0c2d41"}
{"subtype": "task_notification", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubbs7i8-6f0c2d41", "status": "completed"}
{"subtype": "task_started", "task_id": "a5c2e8f41b09d7a36", "run_id": "0mubc18m1-b7719e05"}

ambient הוא true למשימות שאינן חלק מעבודת הסשן, למשל משימות ש-Claude Code מריץ לצורך הפעולה שלו. גם צופי עדכון חי הם ambient, כולל צופים שהמשתמש ביקש. הוצא משימות ambient ממחווני פעילות. השדה דורש Agent SDK מגרסה v0.3.247 ואילך.

ambient מופיע גם ב-SDKTaskNotificationMessage וברשומות SDKBackgroundTasksChangedMessage.

is_backgrounded ו-spawn_depth מתארים איך Claude Code התחיל את המשימה. שני השדות דורשים Agent SDK מגרסה v0.3.238 ואילך.

• is_backgrounded: Claude Code מגדיר אותו על משימות "local_agent" ו-"local_bash". true אומר שהמשימה רצה ברקע. false אומר שהמשימה רצה בחזית, וקריאת הכלי שהתחילה אותה נשארת חסומה עד שהמשימה מסתיימת או עוברת לרקע.
• spawn_depth: Claude Code מגדיר אותו רק על משימות "local_agent". לסוכן משנה שהתהליך הראשי יצר יש עומק 1. לסוכן משנה שסוכן משנה בעומק 1 יצר יש עומק 2, וכן הלאה.

סוכן משנה שהמשיך תמיד מדווח is_backgrounded: true, כי Claude Code מריץ כל סוכן משנה שהמשיך ברקע. כשמשימת חזית עוברת לרקע מאוחר יותר, Claude Code מדווח על ערך is_backgrounded החדש בהודעת task_updated במקום לשלוח task_started שני.

parent_task_id מחזיק את task_id של סוכן המשנה שהפעיל את המשימה הזו. השתמש בו כדי לקבץ כל משימה תחת סוכן המשנה שהתחיל אותה. Claude Code מגדיר אותו על משימות של סוכן משנה, Bash ו-Monitor. השדה דורש Agent SDK מגרסה v0.3.292 ואילך. הוא נעדר כאשר:

• התהליך הראשי הפעיל את המשימה
• Claude Code כבר לא עוקב אחרי משימת האב
• teammate או סוכן בתוך workflow הפעיל את המשימה

האב יכול להיות משימת חזית או משימה שכבר הסתיימה, לכן התייחס למזהה שאינך מזהה כאילו אין אב.

#SDKTaskProgressMessage

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

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

type SDKTaskProgressMessage = {
  type: "system";
  subtype: "task_progress";
  task_id: string;
  run_id?: string;
  tool_use_id?: string;
  description: string;
  subagent_type?: string;
  usage: {
    total_tokens: number;
    tool_uses: number;
    duration_ms: number;
  };
  last_tool_name?: string;
  summary?: string;
  uuid: UUID;
  session_id: string;
};

#SDKTaskUpdatedMessage

נפלט כשמצב של משימת רקע משתנה, למשל כשהיא עוברת מ-running ל-completed. מזג את patch למפת המשימות המקומית שלך לפי מפתח task_id. השדה end_time הוא חותמת זמן של Unix epoch באלפיות השנייה, בר השוואה ל-Date.now(). לשדה run_id ראה SDKTaskStartedMessage, שמגדיר אותו ואת דרישת הגרסה שלו.

type SDKTaskUpdatedMessage = {
  type: "system";
  subtype: "task_updated";
  task_id: string;
  run_id?: string;
  patch: {
    status?: "pending" | "running" | "completed" | "failed" | "killed";
    description?: string;
    end_time?: number;
    total_paused_ms?: number;
    error?: string;
    is_backgrounded?: boolean;
  };
  uuid: UUID;
  session_id: string;
};

#SDKBackgroundTasksChangedMessage

נפלט בכל פעם שקבוצת משימות הרקע החיות משתנה: משימה מתחילה, מסתיימת או נהרגת, סוכן בחזית עובר לרקע, או ששדה description, ambient או parent_task_id של משימה משתנה. לשדות run_id ו-parent_task_id בכל רשומה ראה SDKTaskStartedMessage, שמגדיר אותם ואת דרישות הגרסה שלהם.

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

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

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

כשאתה שולח בקשת בקרה initialize חוזרת לסשן רץ, למשל עם reinitialize() אחרי פער בתעבורה, Claude Code ממשיך אחרי התשובה בצילום מצב של הקבוצה החיה הנוכחית, גם כשהיא ריקה. מארח שמתחבר מחדש לומד כך מה רץ בלי להמתין לשינוי החברות הבא. לפני Agent SDK v0.3.239, Claude Code לא שלח צילום מצב אחרי initialize חוזר.

דורש Claude Code מגרסה v2.1.203 ואילך.

type SDKBackgroundTasksChangedMessage = {
  type: "system";
  subtype: "background_tasks_changed";
  tasks: {
    task_id: string;
    run_id?: string;
    task_type: string;
    subagent_type?: string;
    description: string;
    parent_task_id?: string;
    ambient?: boolean;
  }[];
  uuid: UUID;
  session_id: string;
};

subagent_type מציין את סוג סוכן המשנה ברשומות ש-task_type שלהן הוא "local_agent", למשל general-purpose או השם של סוכן משנה מותאם. השדה דורש Agent SDK מגרסה v0.3.293 ואילך.

#SDKThinkingTokensMessage

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

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

דורש Claude Code מגרסה v2.1.153 ואילך.

type SDKThinkingTokensMessage = {
  type: "system";
  subtype: "thinking_tokens";
  estimated_tokens: number;
  estimated_tokens_delta: number;
  user_message_uuid?: string;
  uuid: UUID;
  session_id: string;
};

#SDKSessionStateChangedMessage

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

השדה state נושא אחד מהערכים האלה:

• running: הסשן עובד.
• idle: Claude Code ממתין להנחיה הבאה שלך.
• requires_action: הסשן חסום על תשובה לבקשה שהוא שלח למארח שלך, למשל בקשת הרשאה.

הודעת idle של תור והודעת result שלו יכולות להגיע בכל סדר. כדי לשנות אם idle ממתין לעבודת רקע כמו סוכן משנה ברקע או ריצת workflow, ראה CLAUDE_CODE_BG_TASKS_REPORT_RUNNING.

type SDKSessionStateChangedMessage = {
  type: "system";
  subtype: "session_state_changed";
  state: "idle" | "running" | "requires_action";
  uuid: UUID;
  session_id: string;
};

#SDKFilesPersistedEvent

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

type SDKFilesPersistedEvent = {
  type: "system";
  subtype: "files_persisted";
  files: { filename: string; file_id: string }[];
  failed: { filename: string; error: string }[];
  processed_at: string;
  uuid: UUID;
  session_id: string;
};

#SDKRateLimitEvent

נפלט כאשר הסשן נתקל במגבלת קצב.

type SDKRateLimitEvent = {
  type: "rate_limit_event";
  rate_limit_info: {
    status: "allowed" | "allowed_warning" | "rejected";
    resetsAt?: number;
    utilization?: number;
    errorCode?: "credits_required";
    canUserPurchaseCredits?: boolean;
    hasChargeableSavedPaymentMethod?: boolean;
  };
  uuid: UUID;
  session_id: string;
};

כאשר errorCode הוא "credits_required", הדחייה מגיעה ממנוי claude.ai שהשימוש הכלול בו מוצה, והסשן לא יכול להמשיך עד שהמשתמש קונה קרדיטים לשימוש. canUserPurchaseCredits מציין אם המשתמש המאומת יכול לקנות קרדיטים לחשבון, ו-hasChargeableSavedPaymentMethod מציין אם אמצעי תשלום שמור קיים בתיק. שלושת השדות נעדרים באירועי מגבלת קצב שאינם דחיות מסוג credits-required. נדרש Claude Code v2.1.181 או חדש יותר.

#SDKLocalCommandOutputMessage

Claude Code לא פולט את סוג ההודעה הזה. כאשר שולחים פקודה כמו /context או /usage כפרומפט, הפלט שלה מגיע כ-SDKAssistantMessage.

type SDKLocalCommandOutputMessage = {
  type: "system";
  subtype: "local_command_output";
  content: string;
  uuid: UUID;
  session_id: string;
};

#SDKCommandsChangedMessage

נפלט כאשר קבוצת הפקודות הזמינות משתנה באמצע הסשן, למשל כאשר Claude Code מגלה skills כשהסוכן נכנס לתת תיקייה. מערך commands הוא הרשימה המעודכנת המלאה, ולכן יש להחליף כל רשימת פקודות שנשמרה במטמון במטען הזה. קריאה ל-supportedCommands() אחרי ההודעה הזו מחזירה את אותה רשימה מעודכנת, כי המתודה עוקבת אחרי הדחיפה האחרונה. זה דורש Agent SDK v0.3.216 או חדש יותר. בגרסאות SDK קודמות, supportedCommands() מחזיר את תצלום המצב שנקלט באתחול ולעולם לא משקף שינויים באמצע הסשן.

Claude Code גם פולט את ההודעה הזו כאשר prompts של שרת MCP מצטרפים לרשימה או עוזבים אותה, למשל כאשר שרת מסיים להתחבר אחרי שהסשן התחיל. זה דורש Claude Code v2.1.281 או חדש יותר.

type SDKCommandsChangedMessage = {
  type: "system";
  subtype: "commands_changed";
  commands: SlashCommand[];
  uuid: UUID;
  session_id: string;
};

#SDKPromptSuggestionMessage

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

type SDKPromptSuggestionMessage = {
  type: "prompt_suggestion";
  suggestion: string;
  uuid: UUID;
  session_id: string;
};

#SDKConversationResetMessage

נפלט כאשר השיחה של הסשן מוחלפת בלי לסיים את הסשן. בקריאה ל-query(), רק /clear והכינויים שלו מייצרים את ההודעה הזו. הצב תמליל ריק תחת new_conversation_id וזרוק כל כותרת סשן שנשמרה במטמון.

type SDKConversationResetMessage = {
  type: "conversation_reset";
  new_conversation_id: UUID;
  uuid: UUID;
  session_id: string;
  trigger?: "clear" | "plan_mode_exit" | "fresh_session" | "onboarding";
  user_message_uuid?: string;
  timestamp?: string;
};

השדות האופציונליים מתארים את האיפוס:

• trigger: מה זרק את השיחה. אפס את התמליל שלך בכל הודעת conversation_reset, כולל הודעה שבה השדה הזה נעדר או נושא ערך שאינך מזהה.
• user_message_uuid: ה-uuid של הודעת המשתמש שנשאה את /clear. השתמש בו כדי להתאים את האיפוס להודעה הזו.
• timestamp: מתי האיפוס קרה, כמחרוזת ISO 8601 ב-UTC. השתמש בו לתצוגה, לא לסידור הודעות.

השדות trigger, user_message_uuid ו-timestamp דורשים Claude Code v2.1.281 או חדש יותר.

הטיפוסים שפורסמו של ה-SDK מכריזים על SDKConversationResetMessage ב-Claude Code v2.1.203 ואילך. לפני v2.1.203, SDKMessage הפנה לטיפוס בלי להכריז עליו, ולכן צמצום על type === "conversation_reset" נכשל בבדיקת טיפוסים כאשר skipLibCheck היה כבוי.

#BUILTIN_TOOL_NAMES ו-LEGACY_TOOL_NAME_ALIASES

השתמש בשני הקבועים האלה כדי לבדוק שמות כלים שהמשתמשים באפליקציה שלך מזינים. שניהם מאייתים כל שם בדרך שבה כותבים אותו בכללי הרשאות, במתאמי hook, ובאפשרויות tools ו-disallowedTools. ייבא אותם מ-@anthropic-ai/claude-agent-sdk או מ-@anthropic-ai/claude-agent-sdk/core. הם דורשים Agent SDK v0.3.301 או חדש יותר והם alpha.

הצהרות הטיפוס של ה-SDK נותנות ל-BUILTIN_TOOL_NAMES טיפוס tuple לקריאה בלבד ול-LEGACY_TOOL_NAME_ALIASES טיפוס רשומה ממחרוזת למחרוזת:

const BUILTIN_TOOL_NAMES: readonly ["Agent", /* ...more names... */ "Write"];
const LEGACY_TOOL_NAME_ALIASES: Readonly<Record<string, string>>;

• BUILTIN_TOOL_NAMES: שמות הכלים המובנים של Claude Code בסדר אלפביתי, כמו Agent, Bash ו-Read. שמות כלי MCP לא כלולים. מכיוון שהטיפוס הוא tuple של ליטרלים של מחרוזת, (typeof BUILTIN_TOOL_NAMES)[number] נותן טיפוס איחוד של השמות
• LEGACY_TOOL_NAME_ALIASES: שמות כלים קודמים שכללי הרשאות, מתאמי hook, והאפשרויות tools ו-disallowedTools עדיין מקבלים. כל מפתח הוא שם קודם והערך שלו הוא השם הנוכחי: לדוגמה, Task ממופה ל-Agent, ו-KillShell ו-KillBash ממופים ל-TaskStop

אפשר לאשר שם באחת משתי בדיקות: BUILTIN_TOOL_NAMES כולל אותו, או Object.hasOwn(LEGACY_TOOL_NAME_ALIASES, name) מחזיר true. שם שנכשל בשתיהן עדיין יכול להיות תקין, כי BUILTIN_TOOL_NAMES משמיט כלי MCP וחלק מהכלים המובנים. אם בונים רשימת דחייה מ-BUILTIN_TOOL_NAMES, Claude עדיין יכול להשתמש בכלים שהקבוע משמיט. כדי לדחות כל כלי, הגדר disallowedTools: ["*"] במקום זאת.

מציאת שם ב-BUILTIN_TOOL_NAMES לא אומרת שלסשן יש את הכלי הזה: TodoWrite מופיע ברשימה אף על פי שהוא מושבת כברירת מחדל. כדי לראות אילו כלים יש לסשן, קרא את מערך tools של SDKSystemMessage שלו. המערך הזה כולל כלי MCP ומציג את כלי Agent כ-Task, ולכן מפה כל שם דרך LEGACY_TOOL_NAME_ALIASES לפני שמשווים אותו ל-BUILTIN_TOOL_NAMES.

#AbortError

מחלקת שגיאה מותאמת לפעולות ביטול.

class AbortError extends Error {}

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

#הגדרת Sandbox

#SandboxSettings

הגדרה להתנהגות sandbox. השתמש בזה כדי להפעיל sandbox לפקודות ולהגדיר הגבלות רשת באופן תכנותי.

type SandboxSettings = {
  enabled?: boolean;
  failIfUnavailable?: boolean;
  autoAllowBashIfSandboxed?: boolean;
  excludedCommands?: string[];
  allowUnsandboxedCommands?: boolean;
  network?: SandboxNetworkConfig;
  filesystem?: SandboxFilesystemConfig;
  ignoreViolations?: Record<string, string[]>;
  enableWeakerNestedSandbox?: boolean;
  allowNestedUserNamespaces?: boolean;
  ripgrep?: { command: string; args?: string[] };
};

[!NOTE]

ה-sandbox תלוי בתמיכת הפלטפורמה, וב-Linux בכלים כמו bubblewrap ו-socat. כאשר enabled הוא true וה-sandbox לא יכול להתחיל, query() מדווח על הודעת result עם subtype: "error_during_execution" והסיבה ב-errors. בקריאת query() של הודעה יחידה, ה-SDK זורק אחרי שהוא מניב את תוצאת השגיאה הזו, ולכן עטוף את הלולאה בבלוק try כדי להמשיך מעבר לה. ראה טיפול בתוצאה לחוזה השגיאה.

כדי לרוץ בלי sandbox, הגדר failIfUnavailable: false.

#דוגמת שימוש