مرجع Agent SDK — تایپ‌اسکریپت

این یک ترجمهٔ غیررسمی از مستندات Claude Code است که توسط مسیر تهیه شده. نسخهٔ مرجع و معتبر، مستندات رسمی انگلیسی است.

نصب

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

یادداشت

این SDK یک باینریِ بومیِ Claude Code را برای پلتفرمت به‌عنوانِ وابستگیِ اختیاری همراه دارد، مثلِ @anthropic-ai/claude-agent-sdk-darwin-arm64. لازم نیست Claude Code را جداگانه نصب کنی. اگر مدیرِ بسته‌ات وابستگی‌های اختیاری را رد کند، SDK خطای Native CLI binary for <platform> not found می‌اندازد؛ در این حالت pathToClaudeCodeExecutable را روی یک باینریِ claudeِ جداگانه‌نصب‌شده تنظیم کن.

کامپایل به یک فایلِ اجراییِ واحد

وقتی برنامه‌ات را با bun build --compile به یک فایلِ اجراییِ تک‌فایلی کامپایل می‌کنی، SDK نمی‌تواند باینریِ همراهِ CLI را در زمانِ اجرا حل کند. require.resolve درونِ فایل‌سیستمِ مجازیِ $bunfsِ فایلِ اجراییِ کامپایل‌شده کار نمی‌کند، پس SDK خطای Native CLI binary for <platform> 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() باینریِ جاسازی‌شده را از فایل‌سیستمِ مجازیِ فایلِ اجراییِ کامپایل‌شده به یک دایرکتوریِ موقتِ هر-کاربر کپی می‌کند و مسیرِ واقعی را برمی‌گرداند. بیرون از یک فایلِ اجراییِ کامپایل‌شده، مسیرِ ورودی را بدونِ تغییر برمی‌گرداند، پس همان کد در توسعه بدونِ تغییر اجرا می‌شود.

هر فایلِ اجراییِ کامپایل‌شده باینریِ یک پلتفرمِ واحد را جاسازی می‌کند. بسته‌ی پلتفرم را در importت با --targetت هم‌خوان کن:

• برای cross-compile، بسته‌ی پلتفرمِ نامنطبق را نصب کن، مثلاً npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force.
• در ویندوز، زیرمسیرِ باینری claude.exe است، مثلاً @anthropic-ai/claude-agent-sdk-win32-x64/claude.exe.

توابع

query()

تابعِ اصلی برای تعامل با Claude Code. یک async generator می‌سازد که پیام‌ها را همان‌طور که می‌رسند استریم می‌کند.

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

پارامترها

پارامتر	تایپ	توضیح
prompt	string | AsyncIterable<SDKUserMessage>	پرامپتِ ورودی به‌صورتِ یک رشته یا async iterable برای حالتِ استریمینگ
options	Options	شیءِ پیکربندیِ اختیاری (تایپِ Options را پایین ببین)

بازگشتی

یک شیءِ Query برمی‌گرداند که AsyncGenerator<SDKMessage, void> را با متدهای اضافی گسترش می‌دهد.

startup()

زیرفرآیندِ CLI را با راه‌اندازیِ آن و کامل‌کردنِ دست‌دادنِ اولیه (initialize handshake) پیش از در دسترس‌بودنِ پرامپت، از پیش گرم می‌کند. هندلِ WarmQueryِ برگشتی بعداً یک پرامپت می‌پذیرد و آن را به یک فرآیندِ از پیش آماده می‌نویسد، پس اولین فراخوانیِ query() بدونِ پرداختِ هزینه‌ی راه‌اندازیِ زیرفرآیند و مقداردهیِ اولیه در همان لحظه حل می‌شود.

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

پارامترها

پارامتر	تایپ	توضیح
options	Options	شیءِ پیکربندیِ اختیاری. همان پارامترِ optionsِ query()
initializeTimeoutMs	number	بیشینه زمان به میلی‌ثانیه برای انتظارِ مقداردهیِ اولیه‌ی زیرفرآیند. پیش‌فرض 60000. اگر مقداردهیِ اولیه به‌موقع کامل نشود، promise با خطای timeout رد می‌شود

بازگشتی

یک Promise<WarmQuery> برمی‌گرداند که وقتی زیرفرآیند راه‌اندازی شد و دست‌دادنِ اولیه‌اش را کامل کرد حل می‌شود.

مثال

startup() را زود صدا بزن، مثلاً در زمانِ بوتِ برنامه، سپس وقتی پرامپت آماده شد روی هندلِ برگشتی .query() را صدا بزن. این، راه‌اندازیِ زیرفرآیند و مقداردهیِ اولیه را از مسیرِ بحرانی خارج می‌کند.

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);
}

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 }
): SdkMcpToolDefinition<Schema>;

پارامترها

پارامتر	تایپ	توضیح
name	string	نامِ ابزار
description	string	توضیحی از کاری که ابزار انجام می‌دهد
inputSchema	Schema extends AnyZodRawShape	اسکیمای Zod که پارامترهای ورودیِ ابزار را تعریف می‌کند (هم از Zod 3 و هم Zod 4 پشتیبانی می‌کند)
handler	(args, extra) => Promise<CallToolResult>	تابعِ async که منطقِ ابزار را اجرا می‌کند
extras	{ annotations?: ToolAnnotations }	annotationهای اختیاریِ ابزارِ MCP که اشاره‌های رفتاری به کلاینت‌ها می‌دهند

ToolAnnotations

از @modelcontextprotocol/sdk/types.js دوباره صادر شده. همه‌ی فیلدها اشاره‌های اختیاری‌اند؛ کلاینت‌ها نباید برای تصمیماتِ امنیتی به آن‌ها تکیه کنند.

فیلد	تایپ	پیش‌فرض	توضیح
title	string	undefined	عنوانِ خوانا برای انسان برای ابزار
readOnlyHint	boolean	false	اگر true باشد، ابزار محیطش را تغییر نمی‌دهد
destructiveHint	boolean	true	اگر true باشد، ابزار ممکن است به‌روزرسانی‌های مخرب انجام دهد (فقط وقتی معنا دارد که readOnlyHint برابرِ false باشد)
idempotentHint	boolean	false	اگر true باشد، فراخوانی‌های مکرر با همان آرگومان‌ها اثرِ اضافی ندارند (فقط وقتی معنا دارد که readOnlyHint برابرِ false باشد)
openWorldHint	boolean	true	اگر true باشد، ابزار با موجودیت‌های بیرونی تعامل می‌کند (مثلاً جستجوی وب). اگر false باشد، دامنه‌ی ابزار بسته است (مثلاً یک ابزارِ حافظه)

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;
  tools?: Array<SdkMcpToolDefinition<any>>;
}): McpSdkServerConfigWithInstance;

پارامترها

پارامتر	تایپ	توضیح
options.name	string	نامِ سرورِ MCP
options.version	string	رشته‌ی نسخه‌ی اختیاری
options.tools	Array<SdkMcpToolDefinition>	آرایه‌ای از تعریفِ ابزارها که با tool() ساخته شده‌اند

listSessions()

نشست‌های گذشته را با فراداده‌ی سبک کشف و فهرست می‌کند. بر اساسِ دایرکتوریِ پروژه فیلتر کن یا نشست‌ها را در سراسرِ همه‌ی پروژه‌ها فهرست کن.

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

پارامترها

پارامتر	تایپ	پیش‌فرض	توضیح
options.dir	string	undefined	دایرکتوری‌ای که نشست‌هایش فهرست شوند. وقتی حذف شود، نشست‌ها را در سراسرِ همه‌ی پروژه‌ها برمی‌گرداند
options.limit	number	undefined	بیشینه‌ی تعدادِ نشست‌هایی که برگردانده شوند
options.includeWorktrees	boolean	true	وقتی dir درونِ یک مخزنِ git است، نشست‌ها را از همه‌ی مسیرهای worktree بگنجان

تایپِ بازگشتی: SDKSessionInfo

خصوصیت	تایپ	توضیح
sessionId	string	شناسه‌ی یکتای نشست (UUID)
summary	string	عنوانِ نمایشی: عنوانِ سفارشی، خلاصه‌ی خودتولید، یا اولین پرامپت
lastModified	number	زمانِ آخرین تغییر به میلی‌ثانیه از epoch
fileSize	number | undefined	اندازه‌ی فایلِ نشست به بایت. فقط برای ذخیره‌سازیِ محلیِ JSONL پر می‌شود
customTitle	string | undefined	عنوانِ نشستِ تنظیم‌شده توسطِ کاربر (از طریقِ /rename)
firstPrompt	string | undefined	اولین پرامپتِ بامعنای کاربر در نشست
gitBranch	string | undefined	شاخه‌ی git در پایانِ نشست
cwd	string | undefined	دایرکتوریِ کاریِ نشست
tag	string | undefined	برچسبِ نشستِ تنظیم‌شده توسطِ کاربر (به tagSession() نگاه کن)
createdAt	number | undefined	زمانِ ساخت به میلی‌ثانیه از epoch، از مهرِ زمانِ اولین ورودی

مثال

۱۰ نشستِ اخیرِ یک پروژه را چاپ کن. نتیجه‌ها بر اساسِ 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[]>;

پارامترها

پارامتر	تایپ	پیش‌فرض	توضیح
sessionId	string	الزامی	UUIDِ نشست برای خواندن (به listSessions() نگاه کن)
options.dir	string	undefined	دایرکتوریِ پروژه برای یافتنِ نشست. وقتی حذف شود، همه‌ی پروژه‌ها را جستجو می‌کند
options.limit	number	undefined	بیشینه‌ی تعدادِ پیام‌هایی که برگردانده شوند
options.offset	number	undefined	تعدادِ پیام‌هایی که از ابتدا رد شوند

تایپِ بازگشتی: SessionMessage

خصوصیت	تایپ	توضیح
type	"user" | "assistant"	نقشِ پیام
uuid	string	شناسه‌ی یکتای پیام
session_id	string	نشستی که این پیام به آن تعلق دارد
message	unknown	محموله‌ی خامِ پیام از رونوشت
parent_tool_use_id	string | null	برای پیام‌های ساب‌ایجنت، tool_use_idِ فراخوانیِ ابزارِ Agentِ سازنده. برای پیام‌های نشستِ اصلی و نشست‌های قدیمی‌تر null است

مثال

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

پارامترها

پارامتر	تایپ	پیش‌فرض	توضیح
sessionId	string	الزامی	UUIDِ نشستی که جستجو شود
options.dir	string	undefined	مسیرِ دایرکتوریِ پروژه. وقتی حذف شود، همه‌ی دایرکتوری‌های پروژه را جستجو می‌کند

یک SDKSessionInfo برمی‌گرداند، یا undefined اگر نشست پیدا نشود.

renameSession()

یک نشست را با افزودنِ یک ورودیِ عنوانِ‌سفارشی تغییرِ‌نام می‌دهد. فراخوانی‌های مکرر امن‌اند؛ تازه‌ترین عنوان برنده است.

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

پارامترها

پارامتر	تایپ	پیش‌فرض	توضیح
sessionId	string	الزامی	UUIDِ نشستی که تغییرِ‌نام داده شود
title	string	الزامی	عنوانِ جدید. باید پس از حذفِ فضاهای خالی ناتهی باشد
options.dir	string	undefined	مسیرِ دایرکتوریِ پروژه. وقتی حذف شود، همه‌ی دایرکتوری‌های پروژه را جستجو می‌کند

tagSession()

به یک نشست برچسب می‌زند. null پاس بده تا برچسب پاک شود. فراخوانی‌های مکرر امن‌اند؛ تازه‌ترین برچسب برنده است.

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

پارامترها

پارامتر	تایپ	پیش‌فرض	توضیح
sessionId	string	الزامی	UUIDِ نشستی که برچسب بخورد
tag	string | null	الزامی	رشته‌ی برچسب، یا null برای پاک‌کردن
options.dir	string	undefined	مسیرِ دایرکتوریِ پروژه. وقتی حذف شود، همه‌ی دایرکتوری‌های پروژه را جستجو می‌کند

resolveSettings()

تنظیماتِ مؤثرِ Claude Code را برای یک دایرکتوریِ معین با همان موتورِ ادغامِ CLI حل می‌کند، بدونِ راه‌اندازیِ CLIِ Claude. از آن استفاده کن تا پیش از فراخوانیِ یک query() بازرسی کنی چه پیکربندی‌ای را خواهد دید.

یادداشت

این تابع آلفا است و API آن ممکن است پیش از پایدارسازی تغییر کند. منابعِ MDM، شاملِ plistِ macOS و HKLM/HKCUِ ویندوز را برای هم‌خوانی با راه‌اندازیِ CLI می‌خواند، اما زیرفرآیندِ policyHelperِ پیکربندی‌شده توسطِ ادمین را اجرا نمی‌کند. فیلدِ permissions.defaultMode همان‌طور که هست از همه‌ی لایه‌ها شاملِ تنظیماتِ پروژه برگردانده می‌شود. فیلترِ اعتمادی که CLI پیش از احترام‌گذاشتن به حالت‌های دسترسیِ تشدیدشونده اعمال می‌کند، اعمال نمی‌شود.

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

پارامترها

resolveSettings() یک شیءِ options واحد می‌پذیرد. همه‌ی فیلدها اختیاری‌اند.

پارامتر	تایپ	پیش‌فرض	توضیح
options.cwd	string	process.cwd()	دایرکتوری‌ای که تنظیماتِ پروژه و محلی نسبت به آن حل شوند
options.settingSources	SettingSource[]	همه‌ی منابع	کدام منابعِ فایل‌سیستمی بارگذاری شوند. [] پاس بده تا تنظیماتِ کاربر، پروژه و محلی رد شوند. تنظیماتِ سیاستِ مدیریت‌شده در همه‌ی حالت‌ها بارگذاری می‌شوند
options.managedSettings	Settings	undefined	تنظیماتِ لایه‌ی سیاستِ محدودکننده که توسطِ میزبانِ جاسازنده فراهم می‌شود. وقتی یک لایه‌ی مدیریت‌شده‌ی مستقرشده توسطِ ادمین حاضر باشد به‌صورتِ پیش‌فرض حذف می‌شود؛ وقتی parentSettingsBehavior برابرِ "merge" باشد زیرِ آن لایه ادغام می‌شود. کلیدهای غیرمحدودکننده مثلِ model بی‌سروصدا حذف می‌شوند پس این گزینه می‌تواند سیاستِ مدیریت‌شده را سخت‌تر کند اما شل‌تر نه
options.serverManagedSettings	Settings	undefined	محموله‌ی تنظیماتِ مدیریت‌شده توسطِ سرور از /api/claude_code/settings. کلیدهای غیرمحدودکننده بدونِ فیلتر عبور می‌کنند

تایپِ بازگشتی: ResolvedSettings

resolveSettings() شیئی برمی‌گرداند که تنظیماتِ ادغام‌شده و منبعی که هر کلید را تأمین کرده توصیف می‌کند.

خصوصیت	تایپ	توضیح
effective	Settings	تنظیماتِ ادغام‌شده پس از اعمالِ همه‌ی منابعِ فعال به ترتیبِ تقدم
provenance	Partial<Record<keyof Settings, ProvenanceEntry>>	برای هر کلیدِ سطحِ‌بالا در effective، این‌که کدام منبع مقدار را تأمین کرده
sources	Array<{ source, settings, path?, policyOrigin? }>	تنظیماتِ خامِ هر-منبع، از پایین‌ترین تا بالاترین تقدم مرتب‌شده

مثال

مثالِ زیر تنظیمات را برای یک دایرکتوریِ پروژه حل می‌کند و منبعی که دوره‌ی پاک‌سازی را کنترل می‌کند چاپ می‌کند.

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

خصوصیت	تایپ	پیش‌فرض	توضیح
abortController	AbortController	new AbortController()	کنترل‌کننده برای لغوِ عملیات
additionalDirectories	string[]	[]	دایرکتوری‌های اضافی که Claude می‌تواند به آن‌ها دسترسی داشته باشد
agent	string	undefined	نامِ ایجنت برای ترِدِ اصلی. ایجنت باید در گزینه‌ی agents یا در تنظیمات تعریف شده باشد
agents	Record<string, [AgentDefinition](#agentdefinition)>	undefined	تعریفِ ساب‌ایجنت‌ها به‌صورتِ برنامه‌نویسی‌شده
agentProgressSummaries	boolean	false	وقتی true باشد، خلاصه‌های پیشرفتِ یک‌خطی برای ساب‌ایجنت‌ها تولید می‌کند و آن‌ها را روی رویدادهای task_progress از طریقِ فیلدِ summary فوروارد می‌کند. روی ساب‌ایجنت‌های پیش‌زمینه و پس‌زمینه اعمال می‌شود
allowDangerouslySkipPermissions	boolean	false	فعال‌کردنِ دورزدنِ دسترسی‌ها. هنگامِ استفاده از permissionMode: 'bypassPermissions' الزامی است
allowedTools	string[]	[]	ابزارهایی که بدونِ پرسش به‌صورتِ خودکار تأیید شوند. این، Claude را به فقط همین ابزارها محدود نمی‌کند؛ ابزارهای فهرست‌نشده به permissionMode و canUseTool می‌رسند. برای مسدودکردنِ ابزارها از disallowedTools استفاده کن. به دسترسی‌ها نگاه کن
betas	SdkBeta[]	[]	فعال‌کردنِ قابلیت‌های بتا
canUseTool	CanUseTool	undefined	تابعِ دسترسیِ سفارشی برای استفاده از ابزار
continue	boolean	false	ادامه‌ی تازه‌ترین گفتگو
cwd	string	process.cwd()	دایرکتوریِ کاریِ فعلی
debug	boolean	false	فعال‌کردنِ حالتِ دیباگ برای فرآیندِ Claude Code
debugFile	string	undefined	نوشتنِ لاگ‌های دیباگ در یک مسیرِ فایلِ مشخص. به‌طورِ ضمنی حالتِ دیباگ را فعال می‌کند
disallowedTools	string[]	[]	ابزارهایی که رد شوند. یک نامِ خالی مثلِ "Bash" ابزار را از کانتکستِ Claude حذف می‌کند. یک قاعده‌ی محدودشده مثلِ "Bash(rm *)" ابزار را در دسترس می‌گذارد و فراخوانی‌های منطبق را در هر حالتِ دسترسی، شاملِ bypassPermissions، رد می‌کند. به دسترسی‌ها نگاه کن
effort	'low' | 'medium' | 'high' | 'xhigh' | 'max'	پیش‌فرضِ مدل	کنترل می‌کند Claude چقدر تلاش در پاسخش می‌گذارد. با تفکرِ تطبیقی کار می‌کند تا عمقِ تفکر را هدایت کند. به تنظیمِ سطحِ تلاش نگاه کن
enableFileCheckpointing	boolean	false	فعال‌کردنِ ردگیریِ تغییرِ فایل برای بازگردانی. به Checkpointingِ فایل نگاه کن
env	Record<string, string | undefined>	process.env	متغیرهای محیطی. وقتی تنظیم شود، این به‌جای ادغام با process.env، محیطِ زیرفرآیند را جایگزین می‌کند، پس { ...process.env, YOUR_VAR: 'value' } پاس بده تا متغیرهای به‌ارث‌رسیده مثلِ PATH حفظ شوند. برای نمونه‌ای از این الگو به مدیریتِ پاسخ‌های کند یا متوقف‌شده‌ی API و برای متغیرهایی که CLIِ زیربنایی می‌خواند به متغیرهای محیطی نگاه کن. CLAUDE_AGENT_SDK_CLIENT_APP را تنظیم کن تا اپت را در هدرِ User-Agent شناسایی کنی
executable	'bun' | 'deno' | 'node'	تشخیصِ خودکار	رانتایمِ JavaScript برای استفاده
executableArgs	string[]	[]	آرگومان‌هایی که به executable پاس داده شوند
extraArgs	Record<string, string | null>	{}	آرگومان‌های اضافی
fallbackModel	string	undefined	مدلی که اگر مدلِ اصلی شکست خورد استفاده شود
forkSession	boolean	false	هنگامِ ادامه با resume، به‌جای ادامه‌ی نشستِ اصلی، به یک شناسه‌ی نشستِ جدید فورک کن
forwardSubagentText	boolean	false	متن و بلاک‌های تفکرِ ساب‌ایجنت را به‌عنوانِ پیام‌های دستیار و کاربر با parent_tool_use_idِ تنظیم‌شده فوروارد می‌کند، تا مصرف‌کنندگان بتوانند یک رونوشتِ تودرتو رندر کنند. به‌صورتِ پیش‌فرض فقط بلاک‌های tool_use و tool_resultِ ساب‌ایجنت‌ها صادر می‌شوند
hooks	Partial<Record<HookEvent, HookCallbackMatcher[]>>	{}	callbackهای hook برای رویدادها
includeHookEvents	boolean	false	رویدادهای چرخه‌ی حیاتِ hook را در استریمِ پیام به‌صورتِ SDKHookStartedMessage، SDKHookProgressMessage و SDKHookResponseMessage بگنجان
includePartialMessages	boolean	false	رویدادهای پیامِ جزئی را بگنجان
loadTimeoutMs	number	60000	آلفا. timeout به میلی‌ثانیه برای هر فراخوانیِ sessionStore.load() و sessionStore.listSubkeys() در طولِ مادی‌سازیِ resume. اگر آداپتور در این بازه ته‌نشین نشود، پرس‌وجو به‌جای معلق‌ماندن شکست می‌خورد. وقتی sessionStore تنظیم نشده باشد نادیده گرفته می‌شود
managedSettings	Settings	undefined	تنظیماتِ لایه‌ی سیاست که توسطِ فرآیندِ والدِ سازنده فراهم می‌شود. وقتی یک لایه‌ی تنظیماتِ مدیریت‌شده‌ی کنترل‌شده توسطِ IT از قبل روی ماشین وجود داشته باشد حذف می‌شود، مگر اینکه آن ادمین با parentSettingsBehavior: 'merge' موافقت کند. به‌هرحال به کلیدهای فقط‌محدودکننده فیلتر می‌شود
maxBudgetUsd	number	undefined	وقتی برآوردِ هزینه‌ی سمتِ‌کلاینت به این مقدارِ USD رسید پرس‌وجو را متوقف کن. با همان برآوردِ total_cost_usd مقایسه می‌شود؛ برای هشدارهای دقت به ردگیریِ هزینه و مصرف نگاه کن
maxThinkingTokens	number	undefined	منسوخ: به‌جایش از thinking استفاده کن. بیشینه‌ی توکن‌ها برای فرآیندِ تفکر
maxTurns	number	undefined	بیشینه‌ی نوبت‌های ایجنتیک (رفت‌و‌برگشت‌های استفاده از ابزار)
mcpServers	Record<string, [McpServerConfig](#mcpserverconfig)>	{}	پیکربندی‌های سرورِ MCP
model	string	پیش‌فرض از CLI	نامِ مستعارِ مدلِ Claude یا نامِ کاملِ مدل. به مقادیرِ پذیرفته‌شده و شناسه‌های مختصِ ارائه‌دهنده نگاه کن
onElicitation	(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>	undefined	callback برای مدیریتِ درخواست‌های elicitationِ MCP. وقتی یک سرورِ MCP درخواستِ ورودیِ کاربر می‌کند و هیچ hookی اول آن را مدیریت نکرده فراخوانی می‌شود. وقتی فراهم نشود، درخواست‌های elicitationِ مدیریت‌نشده به‌صورتِ خودکار رد می‌شوند
outputFormat	{ type: 'json_schema', schema: JSONSchema }	undefined	تعریفِ قالبِ خروجی برای نتیجه‌های ایجنت. برای جزئیات به خروجی‌های ساختاریافته نگاه کن
outputStyle	string	undefined	یک فیلدِ Options نیست. به‌جایش outputStyle را در شیءِ خطیِ settings یا یک فایلِ تنظیمات تعیین کن. به فعال‌سازیِ یک سبکِ خروجی نگاه کن
pathToClaudeCodeExecutable	string	از باینریِ بومیِ همراه به‌صورتِ خودکار حل می‌شود	مسیرِ فایلِ اجراییِ Claude Code. فقط وقتی لازم است که وابستگی‌های اختیاری حینِ نصب رد شده باشند یا پلتفرمت در مجموعه‌ی پشتیبانی‌شده نباشد
permissionMode	PermissionMode	'default'	حالتِ دسترسی برای نشست
permissionPromptToolName	string	undefined	نامِ ابزارِ MCP برای پرسش‌های دسترسی
persistSession	boolean	true	وقتی false باشد، پایداریِ نشست روی دیسک را غیرفعال می‌کند. نشست‌ها بعداً نمی‌توانند ادامه داده شوند
planModeInstructions	string	undefined	دستورالعمل‌های ورک‌فلوِ سفارشی برای حالتِ plan. وقتی permissionMode برابرِ 'plan' باشد، این رشته بدنه‌ی پیش‌فرضِ ورک‌فلوِ حالتِ plan را جایگزین می‌کند. CLI همچنان آن را با پیش‌درآمدِ اعمالِ فقط‌خواندنی و پاورقیِ پروتکلِ ExitPlanMode می‌پیچد
plugins	SdkPluginConfig[]	[]	بارگذاریِ پلاگین‌های سفارشی از مسیرهای محلی. برای جزئیات به پلاگین‌ها نگاه کن
promptSuggestions	boolean	false	فعال‌کردنِ پیشنهادهای پرامپت. پس از هر نوبت یک پیامِ prompt_suggestion با یک پرامپتِ بعدیِ پیش‌بینی‌شده‌ی کاربر صادر می‌کند
resume	string	undefined	شناسه‌ی نشست برای ادامه
resumeSessionAt	string	undefined	ادامه‌ی نشست در یک UUIDِ پیامِ مشخص
sandbox	SandboxSettings	undefined	پیکربندیِ رفتارِ sandbox به‌صورتِ برنامه‌نویسی‌شده. برای جزئیات به تنظیماتِ Sandbox نگاه کن
sessionId	string	خودتولید	استفاده از یک UUIDِ مشخص برای نشست به‌جای خودتولیدِ آن
sessionStore	SessionStore	undefined	رونوشت‌های نشست را به یک بک‌اندِ بیرونی آینه کن تا هر میزبانی بتواند ادامه‌شان دهد. به پایداریِ نشست‌ها در ذخیره‌سازیِ بیرونی نگاه کن
sessionStoreFlush	'batched' | 'eager'	'batched'	آلفا. حالتِ flush برای sessionStore. وقتی sessionStore تنظیم نشده باشد نادیده گرفته می‌شود
settings	string | Settings	undefined	شیءِ خطیِ تنظیمات یا مسیرِ یک فایلِ تنظیمات. لایه‌ی flag-settings را در ترتیبِ تقدم پر می‌کند. با applyFlagSettings() در زمانِ اجرا تغییرش بده
settingSources	SettingSource[]	پیش‌فرض‌های CLI (همه‌ی منابع)	کنترلِ این‌که کدام تنظیماتِ فایل‌سیستمی بارگذاری شوند. [] پاس بده تا تنظیماتِ کاربر، پروژه و محلی غیرفعال شوند. تنظیماتِ سیاستِ مدیریت‌شده به‌هرحال بارگذاری می‌شوند. به استفاده از قابلیت‌های Claude Code نگاه کن
skills	string[] | 'all'	undefined	Skillهای در دسترسِ نشست. 'all' پاس بده تا هر skillِ کشف‌شده فعال شود، یا فهرستی از نام‌های skill. وقتی تنظیم شود، SDK به‌صورتِ خودکار ابزارِ Skill را به allowedTools اضافه می‌کند. اگر tools را هم پاس می‌دهی، 'Skill' را در آن فهرست بگنجان. به Skills نگاه کن
spawnClaudeCodeProcess	(options: SpawnOptions) => SpawnedProcess	undefined	تابعِ سفارشی برای راه‌اندازیِ فرآیندِ Claude Code. برای اجرای Claude Code در VMها، کانتینرها، یا محیط‌های دور استفاده کن
stderr	(data: string) => void	undefined	callback برای خروجیِ stderr
strictMcpConfig	boolean	false	فقط از سرورهای پاس‌شده در mcpServers استفاده کن و .mcp.jsonِ پروژه، تنظیماتِ کاربر، سرورهای MCPِ فراهم‌شده توسطِ پلاگین و connectorهای claude.ai را نادیده بگیر
systemPrompt	string | { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }	undefined (پرامپتِ کمینه)	پیکربندیِ سیستم‌پرامپت. یک رشته برای پرامپتِ سفارشی پاس بده، یا { type: 'preset', preset: 'claude_code' } برای استفاده از سیستم‌پرامپتِ Claude Code. هنگامِ استفاده از شکلِ شیءِ preset، append را اضافه کن تا با دستورالعمل‌های اضافی گسترشش بدهی، و excludeDynamicSections: true را تنظیم کن تا کانتکستِ هر-نشست به اولین پیامِ کاربر منتقل شود برای استفاده‌ی مجددِ بهترِ کشِ پرامپت در ماشین‌ها
taskBudget	{ total: number }	undefined	آلفا. بودجه‌ی وظیفه‌ی سمتِ‌API به توکن. وقتی تنظیم شود، به مدل بودجه‌ی توکنِ باقی‌مانده‌اش گفته می‌شود تا بتواند استفاده از ابزار را تنظیم کند و پیش از محدودیت کار را جمع کند
thinking	ThinkingConfig	{ type: 'adaptive' } برای مدل‌های پشتیبانی‌شده	رفتارِ تفکر/استدلالِ Claude را کنترل می‌کند. برای گزینه‌ها به ThinkingConfig نگاه کن
title	string	undefined	عنوانِ نمایشی برای نشست. هنگامِ ادامه از طریقِ resume یا continue، عنوانِ پایدارشده‌ی نشستِ ادامه‌داده‌شده اولویت دارد؛ برای تغییرِ عنوانِ یک نشستِ موجود از renameSession() استفاده کن
toolAliases	Record<string, string>	undefined	نام‌های ابزارهای توکار را به نام‌های ابزارهای MCP نگاشت کن تا Claude به‌جای ابزارِ توکار، پیاده‌سازیِ MCPِ تو را صدا بزند. مثلاً { Bash: 'mcp__workspace__bash' }
toolConfig	ToolConfig	undefined	پیکربندی برای رفتارِ ابزارِ توکار. برای جزئیات به ToolConfig نگاه کن
tools	string[] | { type: 'preset'; preset: 'claude_code' }	undefined	پیکربندیِ ابزار. یک آرایه از نام‌های ابزار پاس بده یا از preset استفاده کن تا ابزارهای پیش‌فرضِ Claude Code را بگیری

مدیریتِ پاسخ‌های کند یا متوقف‌شده‌ی API

زیرفرآیندِ CLI چند متغیرِ محیطی می‌خواند که timeoutهای API و تشخیصِ توقف را کنترل می‌کنند. آن‌ها را از طریقِ گزینه‌ی env پاس بده:

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: timeoutِ هر-درخواست روی کلاینتِ Anthropic، به میلی‌ثانیه. پیش‌فرض 600000. روی حلقه‌ی اصلی و همه‌ی ساب‌ایجنت‌ها اعمال می‌شود.
• CLAUDE_CODE_MAX_RETRIES: بیشینه‌ی تلاش‌های مجددِ API. پیش‌فرض 10. هر تلاشِ مجدد پنجره‌ی API_TIMEOUT_MSِ خودش را می‌گیرد، پس بدترین حالتِ زمانِ سپری‌شده تقریباً API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1) به‌علاوه‌ی backoff است.
• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: نگهبانِ توقف برای ساب‌ایجنت‌های راه‌اندازی‌شده با run_in_background. پیش‌فرض 600000. با هر رویدادِ استریم ریست می‌شود؛ در صورتِ توقف، ساب‌ایجنت را لغو می‌کند، وظیفه را شکست‌خورده علامت می‌زند و خطا را با هر نتیجه‌ی جزئی به والد نشان می‌دهد. روی ساب‌ایجنت‌های همگام اعمال نمی‌شود.
• CLAUDE_ENABLE_STREAM_WATCHDOG=1 با CLAUDE_STREAM_IDLE_TIMEOUT_MS: وقتی هدرها رسیده‌اند اما بدنه‌ی پاسخ از استریم‌شدن می‌ایستد درخواست را لغو می‌کند. وقتی CLAUDE_ENABLE_STREAM_WATCHDOG تنظیم‌نشده باشد، پیش‌فرض روی APIِ مستقیمِ Anthropic سرورکنترل‌شده و روی سایرِ ارائه‌دهندگان خاموش است. CLAUDE_STREAM_IDLE_TIMEOUT_MS پیش‌فرض 300000 است و به همان کف محدود می‌شود. درخواستِ لغوشده از مسیرِ عادیِ تلاشِ مجدد می‌گذرد.

شیءِ Query

رابطی که تابعِ query() برمی‌گرداند.

interface Query extends AsyncGenerator<SDKMessage, void> {
  interrupt(): Promise<void>;
  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]?: Settings[K] | null }): Promise<void>;
  initializationResult(): Promise<SDKControlInitializeResponse>;
  supportedCommands(): Promise<SlashCommand[]>;
  supportedModels(): Promise<ModelInfo[]>;
  supportedAgents(): Promise<AgentInfo[]>;
  mcpServerStatus(): Promise<McpServerStatus[]>;
  accountInfo(): Promise<AccountInfo>;
  reconnectMcpServer(serverName: string): Promise<void>;
  toggleMcpServer(serverName: string, enabled: boolean): Promise<void>;
  setMcpServers(servers: Record<string, McpServerConfig>): Promise<McpSetServersResult>;
  streamInput(stream: AsyncIterable<SDKUserMessage>): Promise<void>;
  stopTask(taskId: string): Promise<void>;
  close(): void;
}

متدها

متد	توضیح
interrupt()	پرس‌وجو را قطع می‌کند (فقط در حالتِ ورودیِ استریمینگ در دسترس است)
rewindFiles(userMessageId, options?)	فایل‌ها را به وضعیتشان در پیامِ کاربرِ مشخص بازمی‌گرداند. { dryRun: true } پاس بده تا تغییرات را پیش‌نمایش کنی. نیازمندِ enableFileCheckpointing: true. به Checkpointingِ فایل نگاه کن
setPermissionMode()	حالتِ دسترسی را تغییر می‌دهد (فقط در حالتِ ورودیِ استریمینگ در دسترس است)
setModel()	مدل را تغییر می‌دهد (فقط در حالتِ ورودیِ استریمینگ در دسترس است)
setMaxThinkingTokens()	منسوخ: به‌جایش از گزینه‌ی thinking استفاده کن. بیشینه‌ی توکن‌های تفکر را تغییر می‌دهد
applyFlagSettings(settings)	تنظیمات را در زمانِ اجرا در لایه‌ی flag settingsِ نشست ادغام می‌کند (فقط در حالتِ ورودیِ استریمینگ در دسترس است). به applyFlagSettings() نگاه کن
initializationResult()	نتیجه‌ی کاملِ مقداردهیِ اولیه را برمی‌گرداند، شاملِ دستورهای پشتیبانی‌شده، مدل‌ها، اطلاعاتِ حساب و پیکربندیِ سبکِ خروجی
supportedCommands()	دستورهای اسلشِ در دسترس را برمی‌گرداند
supportedModels()	مدل‌های در دسترس را با اطلاعاتِ نمایشی برمی‌گرداند
supportedAgents()	ساب‌ایجنت‌های در دسترس را به‌صورتِ AgentInfo[] برمی‌گرداند
mcpServerStatus()	وضعیتِ سرورهای MCPِ متصل را برمی‌گرداند
accountInfo()	اطلاعاتِ حساب را برمی‌گرداند
reconnectMcpServer(serverName)	اتصالِ مجددِ یک سرورِ MCP با نام
toggleMcpServer(serverName, enabled)	فعال یا غیرفعال‌کردنِ یک سرورِ MCP با نام
setMcpServers(servers)	مجموعه‌ی سرورهای MCPِ این نشست را به‌صورتِ پویا جایگزین می‌کند. اطلاعاتی درباره‌ی این‌که کدام سرورها اضافه، حذف و چه خطاهایی رخ داد برمی‌گرداند
streamInput(stream)	پیام‌های ورودی را برای گفتگوهای چندمرحله‌ای به پرس‌وجو استریم می‌کند
stopTask(taskId)	یک وظیفه‌ی پس‌زمینه‌ی در حالِ اجرا را با شناسه متوقف می‌کند
close()	پرس‌وجو را می‌بندد و فرآیندِ زیربنایی را خاتمه می‌دهد. به‌اجبار پرس‌وجو را پایان می‌دهد و همه‌ی منابع را پاک‌سازی می‌کند

applyFlagSettings()

تنظیمات را روی یک نشستِ در حالِ اجرا بدونِ راه‌اندازیِ مجددِ پرس‌وجو تغییر می‌دهد. وقتی استفاده کن که تنظیمی که setterِ اختصاصی ندارد باید وسطِ نشست عوض شود، مثلِ سخت‌ترکردنِ permissions پس از این‌که ایجنت ورودیِ نامطمئن می‌خواند. setModel() و setPermissionMode() setterهای اختصاصیِ آن دو کلیدند؛ applyFlagSettings() شکلِ کلی است که هر زیرمجموعه‌ای از کلیدهای تنظیمات را می‌پذیرد، و پاس‌دادنِ model اینجا همان رفتارِ setModel() را دارد.

فقط برخی کلیدها وسطِ نشست اثر می‌گذارند:

• در نوبتِ بعدی اعمال می‌شوند: model، effortLevel، ultracode، permissions، hooks، skillOverrides، fastMode، awaySummaryEnabled، agent. تعویضِ agent همچنین بازنویسیِ مدل، hookها و سیستم‌پرامپتِ آن ایجنت را در نوبتِ بعدی اعمال می‌کند.
• وسطِ نشست بی‌اثر: گزینه‌های سیستم‌پرامپت. این‌ها یک‌بار هنگامِ راه‌اندازی حل می‌شوند، پس نشستِ در حالِ اجرا مقدارِ اصلی را نگه می‌دارد حتی اگر فراخوانی موفق باشد. برای تغییرشان، یک نشستِ جدید شروع کن.

مقادیر در لایه‌ی flag-settings نوشته می‌شوند، همان لایه‌ای که گزینه‌ی خطیِ settingsِ query() هنگامِ راه‌اندازی پر می‌کند. flag settings نزدیکِ بالای ترتیبِ تقدمِ تنظیمات قرار دارد: تنظیماتِ کاربر، پروژه و محلی را بازنویسی می‌کند، و فقط تنظیماتِ سیاستِ مدیریت‌شده می‌تواند آن را بازنویسی کند. این همان لایه‌ای است که بخشِ تقدمِ همین صفحه آن را گزینه‌های برنامه‌نویسی‌شده می‌نامد.

فراخوانی‌های پیاپی کلیدهای سطحِ‌بالا را به‌صورتِ کم‌عمق ادغام می‌کنند. یک فراخوانیِ دوم با { permissions: {...} } کلِ شیءِ permissions را از فراخوانیِ قبلی جایگزین می‌کند نه این‌که به‌صورتِ عمیق در آن ادغام شود. برای پاک‌کردنِ یک کلید از لایه‌ی flag و بازگشت به منابعِ کم‌تقدم‌تر، برای آن کلید null پاس بده. پاس‌دادنِ undefined بی‌اثر است چون سریال‌سازیِ JSON آن را حذف می‌کند.

فقط در حالتِ ورودیِ استریمینگ در دسترس است، همان محدودیتِ setModel() و setPermissionMode().

مثالِ زیر مدلِ فعال را وسطِ نشست عوض می‌کند، سپس بازنویسی را پاک می‌کند تا مدل به آن‌چه تنظیماتِ کاربر یا پروژه مشخص می‌کنند برگردد.

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 and fall back to lower-precedence settings
await q.applyFlagSettings({ model: null });

یادداشت

applyFlagSettings() فقط TypeScript است. Python SDK متدِ معادلی ارائه نمی‌دهد.

WarmQuery

هندلی که startup() برمی‌گرداند. زیرفرآیند از قبل راه‌اندازی و مقداردهیِ اولیه شده، پس فراخوانیِ query() روی این هندل پرامپت را مستقیماً به یک فرآیندِ آماده می‌نویسد بدونِ تأخیرِ راه‌اندازی.

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

متدها

متد	توضیح
query(prompt)	یک پرامپت به زیرفرآیندِ از پیش‌گرم‌شده می‌فرستد و یک Query برمی‌گرداند. فقط یک‌بار به‌ازای هر WarmQuery قابلِ‌فراخوانی است
close()	زیرفرآیند را بدونِ فرستادنِ پرامپت می‌بندد. از این برای دورریختنِ یک warm query که دیگر لازم نیست استفاده کن

WarmQuery رابطِ AsyncDisposable را پیاده‌سازی می‌کند، پس می‌توان آن را با await using برای پاک‌سازیِ خودکار استفاده کرد.

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";
};

وقتی یک کلاینت initialize را به نشستی می‌فرستد که از قبل در حالِ اجراست، پوشش‌دهنده‌ی control-response یک آرایه‌ی اختیاریِ pending_permission_requests هم حمل می‌کند. این فیلد روی خودِ پوشش‌دهنده‌ی پاسخ است، نه در محموله‌ی SDKControlInitializeResponseِ بالا. هر ورودی یک پیامِ کاملِ control_request با همان شکلِ { type: "control_request", request_id, request } است که نشست برای درخواست‌های دسترسی حینِ اجرا استریم می‌کند.

این‌ها درخواست‌هایی‌اند که پیش از اتصالِ کلاینت صادر شده‌اند و هنوز منتظرِ پاسخ‌اند، پس این آرایه را بخوان تا پرسش‌های دسترسیِ در حالِ پروازِ بی‌درنگ را نشان بدهی؛ آن‌ها دوباره فرستاده نمی‌شوند.

AgentDefinition

پیکربندی برای یک ساب‌ایجنتِ تعریف‌شده به‌صورتِ برنامه‌نویسی‌شده.

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

فیلد	الزامی	توضیح
description	بله	توضیحِ زبانِ‌طبیعی از این‌که کِی از این ایجنت استفاده شود
tools	خیر	آرایه‌ای از نام‌های ابزارِ مجاز. اگر حذف شود، همه‌ی ابزارها را از والد به ارث می‌برد. برای پیش‌بارگذاریِ Skillها در کانتکستِ ایجنت، از فیلدِ skills استفاده کن نه فهرست‌کردنِ 'Skill' اینجا
disallowedTools	خیر	آرایه‌ای از نام‌های ابزار که صراحتاً برای این ایجنت رد شوند
prompt	بله	سیستم‌پرامپتِ ایجنت
model	خیر	بازنویسیِ مدل برای این ایجنت. یک نامِ مستعار مثلِ 'fable', 'opus', 'sonnet', 'haiku', 'inherit'، یا یک شناسه‌ی کاملِ مدل می‌پذیرد. اگر حذف یا 'inherit' باشد، از مدلِ اصلی استفاده می‌کند
mcpServers	خیر	مشخصاتِ سرورِ MCP برای این ایجنت
skills	خیر	آرایه‌ای از نام‌های skill برای پیش‌بارگذاری در کانتکستِ ایجنت
initialPrompt	خیر	وقتی این ایجنت به‌عنوانِ ایجنتِ ترِدِ اصلی اجرا شود، به‌عنوانِ اولین نوبتِ کاربر به‌صورتِ خودکار ارسال می‌شود
maxTurns	خیر	بیشینه‌ی تعدادِ نوبت‌های ایجنتیک (رفت‌و‌برگشت‌های API) پیش از توقف
background	خیر	این ایجنت را هنگامِ فراخوانی به‌عنوانِ یک وظیفه‌ی پس‌زمینه‌ی غیرمسدودکننده اجرا کن
memory	خیر	منبعِ حافظه برای این ایجنت: 'user', 'project', یا 'local'
effort	خیر	سطحِ تلاشِ استدلال برای این ایجنت. یک سطحِ نام‌گذاری‌شده یا یک عددِ صحیح می‌پذیرد
permissionMode	خیر	حالتِ دسترسی برای اجرای ابزار درونِ این ایجنت. به PermissionMode نگاه کن
criticalSystemReminder_EXPERIMENTAL	خیر	آزمایشی: یادآورِ بحرانی که به سیستم‌پرامپت اضافه می‌شود

AgentMcpServerSpec

سرورهای MCPِ در دسترسِ یک ساب‌ایجنت را مشخص می‌کند. می‌تواند یک نامِ سرور باشد (رشته‌ای که به سروری از پیکربندیِ mcpServersِ والد ارجاع می‌دهد) یا یک رکوردِ پیکربندیِ سرورِ خطی که نام‌های سرور را به پیکربندی‌ها نگاشت می‌کند.

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

که در آن McpServerConfigForProcessTransport برابرِ McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig است.

SettingSource

کنترل می‌کند SDK تنظیمات را از کدام منابعِ پیکربندیِ مبتنی‌بر‌فایل‌سیستم بارگذاری کند.

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

مقدار	توضیح	موقعیت
'user'	تنظیماتِ سراسریِ کاربر	~/.claude/settings.json
'project'	تنظیماتِ مشترکِ پروژه (نسخه‌کنترل‌شده)	.claude/settings.json
'local'	تنظیماتِ محلیِ پروژه (نسخه‌کنترل‌نشده)	.claude/settings.local.json

رفتارِ پیش‌فرض

وقتی settingSources حذف یا undefined باشد، query() همان تنظیماتِ فایل‌سیستمیِ CLIِ Claude Code را بارگذاری می‌کند: کاربر، پروژه و محلی. تنظیماتِ سیاستِ مدیریت‌شده در همه‌ی حالت‌ها بارگذاری می‌شوند. برای ورودی‌هایی که فارغ از این گزینه خوانده می‌شوند و نحوه‌ی غیرفعال‌کردنشان به آن‌چه settingSources کنترل نمی‌کند نگاه کن.

چرا از settingSources استفاده کنیم

غیرفعال‌کردنِ تنظیماتِ فایل‌سیستمی:

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

بارگذاریِ صریحِ همه‌ی تنظیماتِ فایل‌سیستمی:

const result = query({
  prompt: "Analyze this code",
  options: {
    settingSources: ["user", "project", "local"] // Load all settings
  }
});

بارگذاریِ فقط منابعِ تنظیماتِ خاص:

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

محیط‌های تست و CI:

// Ensure consistent behavior in CI by excluding local settings
const result = query({
  prompt: "Run tests",
  options: {
    settingSources: ["project"], // Only team-shared settings
    permissionMode: "bypassPermissions"
  }
});

برنامه‌های فقط-SDK:

// Define everything programmatically.
// Pass [] to opt out of filesystem setting sources.
const result = query({
  prompt: "Review this PR",
  options: {
    settingSources: [],
    agents: {
      /* ... */
    },
    mcpServers: {
      /* ... */
    },
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

بارگذاریِ دستورالعمل‌های پروژه‌ی CLAUDE.md:

// Load project settings to include CLAUDE.md files
const result = query({
  prompt: "Add a new feature following project conventions",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // Use Claude Code's system prompt
    },
    settingSources: ["project"], // Loads CLAUDE.md from project directory
    allowedTools: ["Read", "Write", "Edit"]
  }
});

تقدمِ تنظیمات

وقتی چند منبع بارگذاری می‌شوند، تنظیمات با این تقدم ادغام می‌شوند (بالاترین به پایین‌ترین):

1. تنظیماتِ محلی (.claude/settings.local.json)
2. تنظیماتِ پروژه (.claude/settings.json)
3. تنظیماتِ کاربر (~/.claude/settings.json)

گزینه‌های برنامه‌نویسی‌شده مثلِ agents, allowedTools و settings تنظیماتِ فایل‌سیستمیِ کاربر، پروژه و محلی را بازنویسی می‌کنند. تنظیماتِ سیاستِ مدیریت‌شده بر گزینه‌های برنامه‌نویسی‌شده تقدم دارند.

PermissionMode

type PermissionMode =
  | "default" // Standard permission behavior
  | "acceptEdits" // Auto-accept file edits
  | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt
  | "plan" // Planning mode - explore without editing
  | "dontAsk" // Don't prompt for permissions, deny if not pre-approved
  | "auto"; // Use a model classifier to approve or deny each tool call

CanUseTool

تایپِ تابعِ دسترسیِ سفارشی برای کنترلِ استفاده از ابزار.

type CanUseTool = (
  toolName: string,
  input: Record<string, unknown>,
  options: {
    signal: AbortSignal;
    suggestions?: PermissionUpdate[];
    blockedPath?: string;
    decisionReason?: string;
    toolUseID: string;
    agentID?: string;
  }
) => Promise<PermissionResult>;

گزینه	تایپ	توضیح
signal	AbortSignal	اگر عملیات باید لغو شود سیگنال می‌خورد
suggestions	PermissionUpdate[]	به‌روزرسانی‌های پیشنهادیِ دسترسی تا کاربر دوباره برای این ابزار پرسیده نشود. پرسش‌های Bash یک پیشنهاد با مقصدِ localSettings destination دارند، پس برگرداندنش در updatedPermissions قاعده را در .claude/settings.local.json می‌نویسد و در طولِ نشست‌ها پایدار می‌ماند.
blockedPath	string	مسیرِ فایلی که درخواستِ دسترسی را تحریک کرد، در صورتِ وجود
decisionReason	string	توضیح می‌دهد چرا این درخواستِ دسترسی تحریک شد
toolUseID	string	شناسه‌ی یکتا برای این فراخوانیِ ابزارِ خاص درونِ پیامِ دستیار
agentID	string	اگر درونِ یک ساب‌ایجنت اجرا می‌شود، شناسه‌ی ساب‌ایجنت

PermissionResult

نتیجه‌ی یک بررسیِ دسترسی.

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

ToolConfig

پیکربندی برای رفتارِ ابزارِ توکار.

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

فیلد	تایپ	توضیح
askUserQuestion.previewFormat	'markdown' | 'html'	فیلدِ preview را روی گزینه‌های AskUserQuestion فعال می‌کند و قالبِ محتوایش را تعیین می‌کند. وقتی تنظیم‌نشده باشد، Claude پیش‌نمایش صادر نمی‌کند

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

type McpSdkServerConfigWithInstance = {
  type: "sdk";
  name: string;
  instance: McpServer;
};

McpClaudeAIProxyServerConfig

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

SdkPluginConfig

پیکربندی برای بارگذاریِ پلاگین‌ها در SDK.

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

فیلد	تایپ	توضیح
type	'local'	باید 'local' باشد (در حالِ حاضر فقط پلاگین‌های محلی پشتیبانی می‌شوند)
path	string	مسیرِ مطلق یا نسبی به دایرکتوریِ پلاگین
skipMcpDiscovery	boolean	وقتی true باشد، SDK، skillها، hookها، ایجنت‌ها و دستورها را از این پلاگین بارگذاری می‌کند اما .mcp.json یا mcpServersِ مانیفستش را نمی‌خواند. این را وقتی تنظیم کن که برنامه‌ات مالکِ اتصال‌های MCPِ پلاگین است.

مثال:

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

برای اطلاعاتِ کامل درباره‌ی ساخت و استفاده از پلاگین‌ها، به پلاگین‌ها نگاه کن.

تایپ‌های پیام

SDKMessage

تایپِ اجتماعِ همه‌ی پیام‌های ممکنی که پرس‌وجو برمی‌گرداند.

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

SDKAssistantMessage

پیامِ پاسخِ دستیار.

type SDKAssistantMessage = {
  type: "assistant";
  uuid: UUID;
  session_id: string;
  message: BetaMessage; // From Anthropic SDK
  parent_tool_use_id: string | null;
  error?: SDKAssistantMessageError;
};

فیلدِ message یک BetaMessage از Anthropic SDK است. شاملِ فیلدهایی مثلِ id, content, model, stop_reason و usage است.

SDKAssistantMessageError یکی از این‌هاست: 'authentication_failed', 'oauth_org_not_allowed', 'billing_error', 'rate_limit', 'overloaded', 'invalid_request', 'model_not_found', 'server_error', 'max_output_tokens', یا 'unknown'. 'model_not_found' یعنی مدلِ انتخاب‌شده وجود ندارد یا برای حساب یا استقرارِ تو در دسترس نیست. 'overloaded' یعنی API یک 529 برگرداند چون سرور در ظرفیت است، برخلافِ 'rate_limit' که یک 429 در برابرِ سهمیه‌ی توست.

SDKUserMessage

پیامِ ورودیِ کاربر.

type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_id?: string;
  message: MessageParam; // From Anthropic SDK
  parent_tool_use_id: string | null;
  isSynthetic?: boolean;
  shouldQuery?: boolean;
  tool_use_result?: unknown;
  origin?: SDKMessageOrigin;
};

shouldQuery را روی false تنظیم کن تا پیام بدونِ تحریکِ یک نوبتِ دستیار به رونوشت اضافه شود. پیام نگه داشته می‌شود و در پیامِ کاربرِ بعدی که نوبت را تحریک می‌کند ادغام می‌شود. از این برای تزریقِ کانتکست، مثلِ خروجیِ دستوری که خارج از مسیر اجرا کردی، بدونِ خرجِ یک فراخوانیِ مدل استفاده کن.

SDKUserMessageReplay

پیامِ کاربرِ بازپخش‌شده با UUIDِ الزامی.

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

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;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      structured_output?: unknown;
      deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };
      terminal_reason?: TerminalReason;
      fast_mode_state?: FastModeState;
      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[];
      errors: string[];
      terminal_reason?: TerminalReason;
      fast_mode_state?: FastModeState;
      origin?: SDKMessageOrigin;
    };

چند فیلد روی نتیجه فراتر از subtype جزئیاتِ تشخیصی حمل می‌کنند:

• api_error_status: کدِ وضعیتِ HTTPِ خطای APIی که گفتگو را خاتمه داد. وقتی نوبت بدونِ خطای API پایان یافته غایب یا null است.
• ttft_ms: زمان تا اولین توکن به میلی‌ثانیه، اندازه‌گیری‌شده وقتی اولین پیامِ کاملِ دستیار می‌رسد. فقط روی شاخه‌ی success حاضر است.
• ttft_stream_ms: زمان به میلی‌ثانیه تا اولین رویدادِ استریمِ message_start، وقتی استریمِ پاسخ باز می‌شود. کمتر از ttft_ms؛ شکافِ بینِ این دو، زمانِ صرف‌شده برای استریمِ اولین پیام است. فقط روی شاخه‌ی success حاضر است.
• terminal_reason: چرا حلقه پایان یافت. یکی از "completed", "max_turns", "tool_deferred", "aborted_streaming", "aborted_tools", "hook_stopped", "stop_hook_prevented", "blocking_limit", "rapid_refill_breaker", "prompt_too_long", "image_error", یا "model_error".
• fast_mode_state: یکی از "on", "off", یا "cooldown".

فیلدِ origin، مقدارِ SDKMessageOriginِ پیامِ کاربری را که این نتیجه را تحریک کرد فوروارد می‌کند. وقتی یک وظیفه‌ی پس‌زمینه تمام می‌شود و SDK یک نوبتِ پیگیریِ مصنوعی تزریق می‌کند، SDKResultMessageِ حاصل، origin: { kind: "task-notification" } را حمل می‌کند. این فیلد را بررسی کن تا نتیجه‌هایی که به پرامپتت پاسخ می‌دهند را از نتیجه‌هایی که برای پیگیریِ وظیفه‌ی پس‌زمینه صادر شده‌اند تمیز دهی، تا بتوانی دومی را مسیریابی یا سرکوب کنی. این فیلد برای نتیجه‌هایی که پیش از هر نوبتِ کاربر صادر شده‌اند، مثلِ خطاهای راه‌اندازی، غایب است.

وقتی یک hookِ PreToolUse مقدارِ permissionDecision: "defer" را برمی‌گرداند، نتیجه stop_reason: "tool_deferred" دارد و deferred_tool_use، مقادیرِ id, name و inputِ ابزارِ معلق را حمل می‌کند. این فیلد را بخوان تا درخواست را در UIِ خودت نشان بدهی، سپس با همان session_id ادامه بده تا پیش بروی. برای رفت‌و‌برگشتِ کامل به به تعویق‌انداختنِ یک فراخوانیِ ابزار برای بعد نگاه کن.

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;
  }[];
  model: string;
  permissionMode: PermissionMode;
  slash_commands: string[];
  output_style: string;
  skills: string[];
  plugins: { name: string; path: string }[];
};

SDKPartialAssistantMessage

پیامِ جزئیِ استریمینگ (فقط وقتی includePartialMessages برابرِ true باشد).

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
};

SDKCompactBoundaryMessage

پیامی که مرزِ فشرده‌سازیِ گفتگو را نشان می‌دهد.

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

SDKPluginInstallMessage

رویدادِ پیشرفتِ نصبِ پلاگین. وقتی CLAUDE_CODE_SYNC_PLUGIN_INSTALL تنظیم شده باشد صادر می‌شود، تا برنامه‌ی Agent SDKت بتواند نصبِ پلاگینِ marketplace را پیش از اولین نوبت ردگیری کند. وضعیت‌های started و completed، کلِ نصب را در میان می‌گیرند. وضعیت‌های installed و failed، marketplaceهای جداگانه را گزارش می‌دهند و شاملِ name هستند.

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

SDKPermissionDeniedMessage

رویدادِ استریم که وقتی سیستمِ دسترسی یک فراخوانیِ ابزار را بدونِ پرسشِ تعاملی به‌صورتِ خودکار رد می‌کند صادر می‌شود. از آن برای رندرِ ردشدن در UIت همان‌طور که اتفاق می‌افتد استفاده کن، به‌جای این‌که فقط نتیجه‌ی ابزارِ is_errorی را که در پی می‌آید مشاهده کنی. مسیرِ پرسشِ تعاملی جداگانه از طریقِ callbackِ canUseTool به برنامه‌ات می‌رسد. ردشدن‌هایی که توسطِ یک hookِ PreToolUse صادر می‌شوند از طریقِ این رویداد گزارش نمی‌شوند.

این رویداد نیازمندِ Claude Code نسخه‌ی v2.1.136 یا بالاتر است.

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;
};

فیلد	تایپ	توضیح
tool_name	string	نامِ ابزاری که رد شد
tool_use_id	string	شناسه‌ی بلاکِ tool_useی که این ردشدن پاسخش است
agent_id	string	شناسه‌ی ساب‌ایجنت وقتی فراخوانیِ ردشده درونِ یک ساب‌ایجنت سرچشمه گرفته. فیلدِ روی can_use_tool را برای مسیریابیِ سمتِ‌میزبان آینه می‌کند
decision_reason_type	string	تمایزگر برای مؤلفه‌ای که تصمیم گرفت، مثلِ "rule", "mode", "classifier", یا "asyncAgent"
decision_reason	string	دلیلِ خوانا برای انسان از مؤلفه‌ی تصمیم‌گیرنده، در صورتِ وجود
message	string	پیامِ ردشدن که در tool_result به مدل برگردانده می‌شود

SDKPermissionDenial

اطلاعاتی درباره‌ی یک استفاده از ابزارِ ردشده.

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

SDKMessageOrigin

منشأِ یک پیامِ نقشِ‌کاربر. این به‌صورتِ origin روی SDKUserMessage ظاهر می‌شود و روی SDKResultMessageِ متناظر فوروارد می‌شود تا بتوانی بگویی چه چیزی یک نوبتِ معین را تحریک کرده.

type SDKMessageOrigin =
  | { kind: "human" }
  | { kind: "channel"; server: string }
  | { kind: "peer"; from: string; name?: string }
  | { kind: "task-notification" }
  | { kind: "coordinator" }
  | { kind: "auto-continuation" };

kind	معنا
human	ورودیِ مستقیم از کاربرِ نهایی. روی پیام‌های کاربر، یک originِ غایب هم یعنی ورودیِ انسانی.
channel	پیامی که روی یک channel می‌رسد. server نامِ سرورِ MCPِ منبع است.
peer	برای پیام‌هایی از یک نشستِ ایجنتِ دیگر رزرو شده. from آدرسِ فرستنده و name نامِ نمایشیِ فرستنده در صورتِ وجود است. Agent SDK این منشأ را صادر نمی‌کند؛ آن را به‌عنوانِ منشأِ ناشناخته تلقی کن.
task-notification	نوبتِ مصنوعی که پس از تمام‌شدنِ یک وظیفه‌ی پس‌زمینه تزریق شده. به SDKTaskNotificationMessage نگاه کن.
coordinator	پیامی از یک هماهنگ‌کننده‌ی تیم در یک تیمِ ایجنت.
auto-continuation	نوبتِ مصنوعی که وقتی نشست بدونِ ورودیِ تازه‌ی کاربر ادامه می‌یابد تزریق می‌شود، مثلِ نتیجه‌ی دستوری که یک پرامپتِ پیگیری را تحریک می‌کند.

تایپ‌های Hook

برای راهنمای جامعِ استفاده از hookها با مثال و الگوهای رایج، به راهنمای Hookها نگاه کن.

HookEvent

رویدادهای hookِ در دسترس.

type HookEvent =
  | "PreToolUse"
  | "PostToolUse"
  | "PostToolUseFailure"
  | "PostToolBatch"
  | "Notification"
  | "UserPromptSubmit"
  | "SessionStart"
  | "SessionEnd"
  | "Stop"
  | "SubagentStart"
  | "SubagentStop"
  | "PreCompact"
  | "PermissionRequest"
  | "Setup"
  | "TeammateIdle"
  | "TaskCompleted"
  | "ConfigChange"
  | "WorktreeCreate"
  | "WorktreeRemove"
  | "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
}

HookInput

تایپِ اجتماعِ همه‌ی تایپ‌های ورودیِ hook.

type HookInput =
  | PreToolUseHookInput
  | PostToolUseHookInput
  | PostToolUseFailureHookInput
  | PostToolBatchHookInput
  | NotificationHookInput
  | UserPromptSubmitHookInput
  | SessionStartHookInput
  | SessionEndHookInput
  | StopHookInput
  | SubagentStartHookInput
  | SubagentStopHookInput
  | PreCompactHookInput
  | PermissionRequestHookInput
  | SetupHookInput
  | TeammateIdleHookInput
  | TaskCompletedHookInput
  | ConfigChangeHookInput
  | WorktreeCreateHookInput
  | WorktreeRemoveHookInput
  | MessageDisplayHookInput;

BaseHookInput

رابطِ پایه که همه‌ی تایپ‌های ورودیِ hook آن را گسترش می‌دهند.

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

PreToolUseHookInput

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

PostToolUseHookInput

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

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;
};

PostToolBatchHookInput

یک‌بار پس از این‌که هر فراخوانیِ ابزار در یک بسته (batch) حل شد، پیش از درخواستِ مدلِ بعدی، فعال می‌شود. 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;
};

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;
};

SessionStartHookInput

type SessionStartHookInput = BaseHookInput & {
  hook_event_name: "SessionStart";
  source: "startup" | "resume" | "clear" | "compact";
  agent_type?: string;
  model?: 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[];
};

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;
};

PermissionRequestHookInput

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

SetupHookInput

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

TeammateIdleHookInput

type TeammateIdleHookInput = BaseHookInput & {
  hook_event_name: "TeammateIdle";
  teammate_name: string;
  team_name: string;
};

TaskCompletedHookInput

type TaskCompletedHookInput = BaseHookInput & {
  hook_event_name: "TaskCompleted";
  task_id: string;
  task_subject: string;
  task_description?: string;
  teammate_name?: string;
  team_name?: string;
};

ConfigChangeHookInput

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

WorktreeCreateHookInput

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

WorktreeRemoveHookInput

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

MessageDisplayHookInput

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

HookJSONOutput

مقدارِ بازگشتیِ hook.

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;
  reason?: string;
  hookSpecificOutput?:
    | {
        hookEventName: "PreToolUse";
        permissionDecision?: "allow" | "deny" | "ask" | "defer";
        permissionDecisionReason?: string;
        updatedInput?: Record<string, unknown>;
        additionalContext?: string;
      }
    | {
        hookEventName: "UserPromptSubmit";
        additionalContext?: string;
      }
    | {
        hookEventName: "SessionStart";
        additionalContext?: string;
      }
    | {
        hookEventName: "Setup";
        additionalContext?: string;
      }
    | {
        hookEventName: "SubagentStart";
        additionalContext?: string;
      }
    | {
        hookEventName: "PostToolUse";
        additionalContext?: string;
        updatedToolOutput?: unknown;
        /** @deprecated Use `updatedToolOutput`, which works for all tools. */
        updatedMCPToolOutput?: unknown;
      }
    | {
        hookEventName: "PostToolUseFailure";
        additionalContext?: string;
      }
    | {
        hookEventName: "PostToolBatch";
        additionalContext?: string;
      }
    | {
        hookEventName: "Notification";
        additionalContext?: string;
      }
    | {
        hookEventName: "PermissionRequest";
        decision:
          | {
              behavior: "allow";
              updatedInput?: Record<string, unknown>;
              updatedPermissions?: PermissionUpdate[];
            }
          | {
              behavior: "deny";
              message?: string;
              interrupt?: boolean;
            };
      };
};

تایپ‌های ورودیِ ابزار

مستندِ اسکیماهای ورودی برای همه‌ی ابزارهای توکارِ Claude Code. این تایپ‌ها از @anthropic-ai/claude-agent-sdk صادر می‌شوند و می‌توان از آن‌ها برای تعامل‌های امن‌از‌نظرِ‌تایپ با ابزارها استفاده کرد.

ToolInputSchemas

اجتماعِ همه‌ی تایپ‌های ورودیِ ابزار، صادرشده از @anthropic-ai/claude-agent-sdk.

type ToolInputSchemas =
  | AgentInput
  | AskUserQuestionInput
  | BashInput
  | TaskOutputInput
  | EnterWorktreeInput
  | ExitPlanModeInput
  | FileEditInput
  | FileReadInput
  | FileWriteInput
  | GlobInput
  | GrepInput
  | ListMcpResourcesInput
  | McpInput
  | MonitorInput
  | NotebookEditInput
  | ReadMcpResourceInput
  | SubscribeMcpResourceInput
  | SubscribePollingInput
  | TaskCreateInput
  | TaskGetInput
  | TaskListInput
  | TaskStopInput
  | TaskUpdateInput
  | TodoWriteInput
  | UnsubscribeMcpResourceInput
  | UnsubscribePollingInput
  | WebFetchInput
  | WebSearchInput
  | WorkflowInput;

Agent

نامِ ابزار: Agent (قبلاً Task، که هنوز به‌عنوانِ نامِ مستعار پذیرفته می‌شود)

type AgentInput = {
  description: string;
  prompt: string;
  subagent_type: string;
  model?: "sonnet" | "opus" | "haiku" | "fable";
  resume?: string;
  run_in_background?: boolean;
  max_turns?: number;
  name?: string;
  team_name?: string;
  mode?: "acceptEdits" | "bypassPermissions" | "default" | "dontAsk" | "plan";
  isolation?: "worktree";
};

یک ایجنتِ جدید برای مدیریتِ خودمختارِ وظایفِ پیچیده و چندگامی راه‌اندازی می‌کند.

AskUserQuestion

نامِ ابزار: AskUserQuestion

type AskUserQuestionInput = {
  questions: Array<{
    question: string;
    header: string;
    options: Array<{ label: string; description: string; preview?: string }>;
    multiSelect: boolean;
  }>;
};

حینِ اجرا از کاربر پرسش‌های روشن‌گرانه می‌پرسد. برای جزئیاتِ استفاده به مدیریتِ تأییدها و ورودیِ کاربر نگاه کن.

Bash

نامِ ابزار: Bash

type BashInput = {
  command: string;
  timeout?: number;
  description?: string;
  run_in_background?: boolean;
  dangerouslyDisableSandbox?: boolean;
};

دستورهای bash را در یک نشستِ شِلِ پایدار با timeout و اجرای پس‌زمینه‌ی اختیاری اجرا می‌کند.

Monitor

نامِ ابزار: Monitor

type MonitorInput = {
  command: string;
  description: string;
  timeout_ms?: number;
  persistent?: boolean;
};

یک اسکریپتِ پس‌زمینه اجرا می‌کند و هر خطِ stdout را به‌عنوانِ یک رویداد به Claude تحویل می‌دهد تا بتواند بدونِ poll واکنش نشان دهد. برای پایش‌های به‌طولِ‌نشست مثلِ دنبال‌کردنِ لاگ، persistent: true را تنظیم کن. Monitor از همان قواعدِ دسترسیِ Bash پیروی می‌کند. برای رفتار و در دسترس‌بودنِ ارائه‌دهنده به مرجعِ ابزارِ Monitor نگاه کن.

TaskOutput

نامِ ابزار: TaskOutput

type TaskOutputInput = {
  task_id: string;
  block: boolean;
  timeout: number;
};

خروجی را از یک وظیفه‌ی پس‌زمینه‌ی در حالِ اجرا یا کامل‌شده بازیابی می‌کند.

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;
};

فایل‌ها را از فایل‌سیستمِ محلی می‌خواند، شاملِ متن، تصویر، PDF و دفترچه‌های Jupyter. از pages برای بازه‌های صفحه‌ی PDF استفاده کن (مثلاً "1-5").

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;
  "-n"?: boolean;
  "-B"?: number;
  "-A"?: number;
  "-C"?: number;
  context?: number;
  head_limit?: number;
  offset?: number;
  multiline?: boolean;
};

ابزارِ جستجوی قدرتمند مبتنی‌بر ripgrep با پشتیبانیِ regex.

TaskStop

نامِ ابزار: TaskStop

type TaskStopInput = {
  task_id?: string;
  shell_id?: string; // Deprecated: use 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;
};

محتوا را از یک URL می‌گیرد و با یک مدلِ AI پردازشش می‌کند.

WebSearch

نامِ ابزار: WebSearch

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

وب را جستجو می‌کند و نتیجه‌های قالب‌بندی‌شده برمی‌گرداند.

Workflow

نامِ ابزار: Workflow

type WorkflowInput = {
  script?: string;
  name?: string;
  scriptPath?: string;
  args?: unknown;
  resumeFromRunId?: string;
};

یک ورک‌فلوِ پویا اجرا می‌کند: اسکریپتی که چند ساب‌ایجنت را در پس‌زمینه هماهنگ می‌کند و یک نتیجه‌ی تلفیق‌شده برمی‌گرداند. ابزارِ Workflow در Agent SDK نسخه‌ی v0.3.149 و بالاتر در دسترس است. حداقل یکی از script, name, یا scriptPath الزامی است.

فیلد	تایپ	توضیح
script	string	اسکریپتِ خطیِ ورک‌فلو. باید با export const meta = { name, description, phases } به‌صورتِ literal شروع شود، سپس بدنه‌ی اسکریپت با استفاده از agent(), parallel(), pipeline() و phase()
name	string	نامِ یک ورک‌فلوِ توکار یا یکی که در .claude/workflows/ ذخیره شده. به یک اسکریپت حل می‌شود
scriptPath	string	مسیرِ یک فایلِ اسکریپتِ ورک‌فلو روی دیسک. بر script و name تقدم دارد. هر فراخوانی اسکریپتش را پایدار می‌کند و مسیر را در نتیجه برمی‌گرداند، پس می‌توانی آن فایل را ویرایش کنی و با همان scriptPath دوباره فراخوانی کنی تا تکرار شود
args	unknown	مقدارِ ورودی که به اسکریپت به‌عنوانِ argsِ سراسری نمایش داده می‌شود، برای ورک‌فلوهای نام‌گذاری‌شده‌ی پارامتری مثلِ یک سوالِ پژوهشی یا فهرستی از مسیرهای فایل. آرایه‌ها و شیءها را به‌عنوانِ مقادیرِ واقعیِ JSON پاس بده، نه به‌صورتِ یک رشته‌ی JSON-encoded
resumeFromRunId	string	شناسه‌ی اجرای یک فراخوانیِ Workflowِ قبلی برای ادامه. فراخوانی‌های agent()ِ کامل‌شده با ورودی‌های بدونِ‌تغییر نتیجه‌های کش‌شده را برمی‌گردانند؛ فقط فراخوانی‌های تغییریافته یا جدید زنده اجرا می‌شوند. فقط همان نشست

TodoWrite

نامِ ابزار: TodoWrite

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

یک فهرستِ وظایفِ ساختاریافته برای ردگیریِ پیشرفت می‌سازد و مدیریت می‌کند.

یادداشت

از TypeScript Agent SDK نسخه‌ی 0.3.142، TodoWrite به‌صورتِ پیش‌فرض غیرفعال است. به‌جایش از TaskCreate, TaskGet, TaskUpdate و TaskList استفاده کن. برای به‌روزرسانیِ کدِ پایشت به مهاجرت به ابزارهای Task نگاه کن، یا CLAUDE_CODE_ENABLE_TASKS=0 را تنظیم کن تا به TodoWrite برگردی.

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 = {};

یک snapshot از همه‌ی وظایفِ فهرستِ فعلی را برمی‌گرداند.

ExitPlanMode

نامِ ابزار: ExitPlanMode

type ExitPlanModeInput = {
  allowedPrompts?: Array<{
    tool: "Bash";
    prompt: string;
  }>;
};

از حالتِ planning خارج می‌شود. به‌صورتِ اختیاری دسترسی‌های مبتنی‌بر‌پرامپتِ لازم برای پیاده‌سازیِ طرح را مشخص می‌کند.

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ِ موجودِ مخزنِ فعلی سوییچ کنی. name و path متقابلاً انحصاری‌اند.

تایپ‌های خروجیِ ابزار

مستندِ اسکیماهای خروجی برای همه‌ی ابزارهای توکارِ Claude Code. این تایپ‌ها از @anthropic-ai/claude-agent-sdk صادر می‌شوند و داده‌ی پاسخِ واقعیِ هر ابزار را نشان می‌دهند.

ToolOutputSchemas

اجتماعِ همه‌ی تایپ‌های خروجیِ ابزار.

type ToolOutputSchemas =
  | AgentOutput
  | AskUserQuestionOutput
  | BashOutput
  | EnterWorktreeOutput
  | ExitPlanModeOutput
  | FileEditOutput
  | FileReadOutput
  | FileWriteOutput
  | GlobOutput
  | GrepOutput
  | ListMcpResourcesOutput
  | MonitorOutput
  | NotebookEditOutput
  | ReadMcpResourceOutput
  | TaskCreateOutput
  | TaskGetOutput
  | TaskListOutput
  | TaskStopOutput
  | TaskUpdateOutput
  | TodoWriteOutput
  | WebFetchOutput
  | WebSearchOutput
  | WorkflowOutput;

Agent

نامِ ابزار: Agent (قبلاً Task، که هنوز به‌عنوانِ نامِ مستعار پذیرفته می‌شود)

type AgentOutput =
  | {
      status: "completed";
      agentId: string;
      content: Array<{ type: "text"; text: string }>;
      resolvedModel?: 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: ("standard" | "priority" | "batch") | null;
        cache_creation: {
          ephemeral_1h_input_tokens: number;
          ephemeral_5m_input_tokens: number;
        } | null;
      };
      prompt: string;
    }
  | {
      status: "async_launched";
      agentId: string;
      description: string;
      resolvedModel?: string;
      prompt: string;
      outputFile: string;
      canReadOutputFile?: boolean;
    }
  | {
      status: "sub_agent_entered";
      description: string;
      message: string;
    };

نتیجه را از ساب‌ایجنت برمی‌گرداند. بر اساسِ فیلدِ status تمایز می‌یابد: "completed" برای وظایفِ تمام‌شده، "async_launched" برای وظایفِ پس‌زمینه، و "sub_agent_entered" برای ساب‌ایجنت‌های تعاملی.

فیلدِ resolvedModel روی واریانت‌های completed و async_launched، مدلی را که ساب‌ایجنت واقعاً روی آن اجرا شد نام می‌برد، که می‌تواند با ورودیِ modelِ درخواست‌شده فرق کند وقتی availableModels یا یک بازنویسیِ دیگر اعمال شود. این فیلد نیازمندِ Claude Code نسخه‌ی v2.1.174 یا بالاتر است.

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;
};

پرسش‌های پرسیده‌شده و پاسخ‌های کاربر را برمی‌گرداند. response وقتی تنظیم می‌شود که کاربر به‌جای پاسخ به پرسش‌های ساختاریافته یک پاسخِ آزاد تایپ کرده باشد؛ وقتی حاضر باشد، Claude به‌جای فهرستِ پاسخِ هر-پرسش، «The user responded: …» را دریافت می‌کند.

Bash

نامِ ابزار: Bash

type BashOutput = {
  stdout: string;
  stderr: string;
  rawOutputPath?: string;
  interrupted: boolean;
  isImage?: boolean;
  backgroundTaskId?: string;
  backgroundedByUser?: boolean;
  dangerouslyDisableSandbox?: boolean;
  returnCodeInterpretation?: string;
  structuredContent?: unknown[];
  persistedOutputPath?: string;
  persistedOutputSize?: number;
};

خروجیِ دستور را با تفکیکِ stdout/stderr برمی‌گرداند. دستورهای پس‌زمینه یک backgroundTaskId در بر دارند.

Monitor

نامِ ابزار: Monitor

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

شناسه‌ی وظیفه‌ی پس‌زمینه را برای monitorِ در حالِ اجرا برمی‌گرداند. از این شناسه با TaskStop برای لغوِ زودهنگامِ پایش استفاده کن.

Edit

نامِ ابزار: Edit

type FileEditOutput = {
  filePath: string;
  oldString: string;
  newString: string;
  originalFile: string;
  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;
  };
};

diffِ ساختاریافته‌ی عملیاتِ ویرایش را برمی‌گرداند.

Read

نامِ ابزار: Read

type FileReadOutput =
  | {
      type: "text";
      file: {
        filePath: string;
        content: string;
        numLines: number;
        startLine: number;
        totalLines: number;
      };
    }
  | {
      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;
      };
    };

محتوای فایل را در قالبی مناسبِ نوعِ فایل برمی‌گرداند. بر اساسِ فیلدِ 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;
  };
};

نتیجه‌ی نوشتن را با اطلاعاتِ diffِ ساختاریافته برمی‌گرداند.

Glob

نامِ ابزار: Glob

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

مسیرهای فایلِ منطبق با الگوی glob را برمی‌گرداند، مرتب‌شده بر اساسِ زمانِ تغییر.

Grep

نامِ ابزار: Grep

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

نتیجه‌های جستجو را برمی‌گرداند. شکل بسته به mode فرق می‌کند: فهرستِ فایل، محتوا با تطبیق‌ها، یا تعدادِ تطبیق‌ها.

TaskStop

نامِ ابزار: TaskStop

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

پس از متوقف‌کردنِ وظیفه‌ی پس‌زمینه تأیید برمی‌گرداند.

NotebookEdit

نامِ ابزار: NotebookEdit

type NotebookEditOutput = {
  new_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;
};

محتوای گرفته‌شده را با وضعیتِ HTTP و فراداده برمی‌گرداند.

WebSearch

نامِ ابزار: WebSearch

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

نتیجه‌های جستجو را از وب برمی‌گرداند.

Workflow

نامِ ابزار: Workflow

type WorkflowOutput = {
  status: "async_launched";
  taskId: string;
  runId?: string;
  summary?: string;
  transcriptDir?: string;
  scriptPath?: string;
  error?: string;
};

بلافاصله پس از این‌که ابزار فراخوانی را پذیرفت برمی‌گردد. نتیجه‌ی نهایی بعداً به‌عنوانِ تکمیلِ وظیفه می‌رسد. پیش از تلقیِ اجرا به‌عنوانِ شروع‌شده، error را بررسی کن: اسکریپتی که در بررسیِ نحویش شکست بخورد status: "async_launched" با errorِ تنظیم‌شده برمی‌گرداند و هرگز اجرا نمی‌شود.

فیلد	تایپ	توضیح
status	"async_launched"	ابزار فراخوانی را پذیرفت. این تنها مقداری است که این فیلد می‌گیرد
taskId	string	شناسه‌ی وظیفه‌ی پس‌زمینه برای اجرا
runId	string	شناسه‌ی اجرای ورک‌فلو برای پاس‌دادن به‌عنوانِ resumeFromRunId در یک فراخوانیِ بعدی
summary	string	توضیحِ یک‌خطی از کاری که ورک‌فلو انجام می‌دهد
transcriptDir	string	دایرکتوری‌ای که رونوشت‌های ساب‌ایجنت حینِ اجرا در آن نوشته می‌شوند
scriptPath	string	مسیرِ اسکریپتِ پایدارشده‌ی ورک‌فلو برای این اجرا. ویرایشش کن و به‌عنوانِ scriptPath برگردان تا بدونِ ارسالِ مجددِ اسکریپت دوباره اجرا شود
error	string	وقتی اسکریپت در بررسیِ نحویش شکست بخورد تنظیم می‌شود. وقتی حاضر باشد، اجرا با وجودِ وضعیتِ async_launched شروع نشده

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;
  }>;
};

فهرستِ وظایفِ قبلی و به‌روزشده را برمی‌گرداند.

یادداشت

از TypeScript Agent SDK نسخه‌ی 0.3.142، TodoWrite به‌صورتِ پیش‌فرض غیرفعال است. به‌جایش از TaskCreate, TaskGet, TaskUpdate و TaskList استفاده کن. برای به‌روزرسانیِ کدِ پایشت به مهاجرت به ابزارهای Task نگاه کن، یا CLAUDE_CODE_ENABLE_TASKS=0 را تنظیم کن تا به TodoWrite برگردی.

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[];
  }>;
};

یک snapshot از همه‌ی وظایفِ فهرستِ فعلی را برمی‌گرداند.

ExitPlanMode

نامِ ابزار: ExitPlanMode

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

وضعیتِ طرح را پس از خروج از حالتِ plan برمی‌گرداند.

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;
  }>;
};

محتوای منبعِ MCPِ درخواست‌شده را برمی‌گرداند.

EnterWorktree

نامِ ابزار: EnterWorktree

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

اطلاعاتی درباره‌ی git worktree برمی‌گرداند.

تایپ‌های دسترسی

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

type ApiKeySource = "user" | "project" | "org" | "temporary" | "oauth";

SdkBeta

قابلیت‌های بتای در دسترس که می‌توان از طریقِ گزینه‌ی betas فعال کرد. برای اطلاعاتِ بیشتر به هدرهای بتا نگاه کن.

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

احتیاط

بتای context-1m-2025-08-07 از ۳۰ آوریلِ ۲۰۲۶ بازنشسته شده است. پاس‌دادنِ این مقدار با Claude Sonnet 4.5 یا Sonnet 4 بی‌اثر است، و درخواست‌هایی که از پنجره‌ی کانتکستِ استانداردِ ۲۰۰هزار توکن فراتر بروند خطا برمی‌گردانند. برای استفاده از پنجره‌ی کانتکستِ ۱ میلیون توکنی، به Claude Sonnet 4.6، Claude Opus 4.6، Claude Opus 4.7 یا Claude Opus 4.8 مهاجرت کن، که کانتکستِ ۱ میلیونی را با قیمت‌گذاریِ استاندارد و بدونِ نیاز به هدرِ بتا در بر دارند.

SlashCommand

اطلاعاتی درباره‌ی یک دستورِ اسلشِ در دسترس.

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

ModelInfo

اطلاعاتی درباره‌ی یک مدلِ در دسترس.

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

AgentInfo

اطلاعاتی درباره‌ی یک ساب‌ایجنتِ در دسترس که می‌توان از طریقِ ابزارِ Agent فراخوانی‌اش کرد.

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

فیلد	تایپ	توضیح
name	string	شناسه‌ی نوعِ ایجنت (مثلاً "Explore", "general-purpose")
description	string	توضیحِ این‌که کِی از این ایجنت استفاده شود
model	string | undefined	نامِ مستعارِ مدلی که این ایجنت استفاده می‌کند. اگر حذف شود، مدلِ والد را به ارث می‌برد

McpServerStatus

وضعیتِ یک سرورِ MCPِ متصل.

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

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 یک برآوردِ سمتِ‌کلاینت است. برای هشدارهای صورتحساب به ردگیریِ هزینه و مصرف نگاه کن.

type ModelUsage = {
  inputTokens: number;
  outputTokens: number;
  cacheReadInputTokens: number;
  cacheCreationInputTokens: number;
  webSearchRequests: number;
  costUSD: number;
  contextWindow: number;
  maxOutputTokens: number;
};

ConfigScope

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

NonNullableUsage

نسخه‌ای از Usage که همه‌ی فیلدهای nullable در آن non-nullable شده‌اند.

type NonNullableUsage = {
  [K in keyof Usage]: 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;
};

BetaServerToolUsage و BetaIterationsUsage در @anthropic-ai/sdk تعریف شده‌اند.

CallToolResult

تایپِ نتیجه‌ی ابزارِ MCP (از @modelcontextprotocol/sdk/types.js). structuredContent یک شیءِ JSON است که می‌توان آن را در کنارِ content برگرداند، شاملِ بلاک‌های تصویر. به برگرداندنِ داده‌ی ساختاریافته نگاه کن.

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

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 دریافت کنی.

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

گزینه‌هایی که به تابعِ راه‌اندازیِ سفارشی پاس داده می‌شوند.

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

یادداشت

فیلدِ signal به تابعِ راه‌اندازیت می‌گوید کِی فرآیند را برچیند. آن را به‌عنوانِ گزینه‌ی signal به spawn()ِ Node پاس بده، یا آن را به هندلرِ برچیدنِ VM یا کانتینرت پاس بده.

این سیگنال لحظه‌ای که Options.abortController لغو می‌شود فعال نمی‌شود. SDK اول stdinِ فرآیند را می‌بندد و حدودِ دو ثانیه صبر می‌کند تا CLI تمیز خاموش شود، سپس این سیگنال را لغو می‌کند. برای واکنش لحظه‌ای که فراخواننده لغو می‌کند، به‌جایش روی Options.abortController.signalِ خودت گوش بده، که تابعِ راه‌اندازیت می‌تواند از دامنه‌ی دربرگیرنده‌اش به آن ارجاع دهد.

McpSetServersResult

نتیجه‌ی یک عملیاتِ setMcpServers().

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

RewindFilesResult

نتیجه‌ی یک عملیاتِ rewindFiles().

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

SDKStatusMessage

پیامِ به‌روزرسانیِ وضعیت (مثلاً در حالِ فشرده‌سازی).

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

SDKTaskNotificationMessage

اعلان وقتی یک وظیفه‌ی پس‌زمینه کامل، شکست، یا متوقف می‌شود. وظایفِ پس‌زمینه شاملِ دستورهای Bashِ run_in_background، پایش‌های Monitor و ساب‌ایجنت‌های پس‌زمینه هستند.

type SDKTaskNotificationMessage = {
  type: "system";
  subtype: "task_notification";
  task_id: string;
  tool_use_id?: string;
  status: "completed" | "failed" | "stopped";
  output_file: string;
  summary: string;
  usage?: {
    total_tokens: number;
    tool_uses: number;
    duration_ms: number;
  };
  uuid: UUID;
  session_id: string;
};

SDKToolUseSummaryMessage

خلاصه‌ی استفاده از ابزار در یک گفتگو.

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

SDKHookStartedMessage

وقتی یک hook شروع به اجرا می‌کند صادر می‌شود.

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;
  uuid: UUID;
  session_id: string;
};

SDKAuthStatusMessage

حین جریان‌های احرازِ هویت صادر می‌شود.

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

SDKTaskStartedMessage

وقتی یک وظیفه‌ی پس‌زمینه شروع می‌شود صادر می‌شود. فیلدِ task_type برای دستورهای Bashِ پس‌زمینه و پایش‌های Monitor برابرِ "local_bash"، برای ساب‌ایجنت‌ها "local_agent"، یا "remote_agent" است.

type SDKTaskStartedMessage = {
  type: "system";
  subtype: "task_started";
  task_id: string;
  tool_use_id?: string;
  description: string;
  task_type?: string;
  uuid: UUID;
  session_id: string;
};

SDKTaskProgressMessage

به‌صورتِ دوره‌ای حین اجرای یک ساب‌ایجنت یا وظیفه‌ی پس‌زمینه صادر می‌شود. فیلدِ summary فقط وقتی agentProgressSummaries فعال باشد پر می‌شود.

type SDKTaskProgressMessage = {
  type: "system";
  subtype: "task_progress";
  task_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().

type SDKTaskUpdatedMessage = {
  type: "system";
  subtype: "task_updated";
  task_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;
};

SDKFilesPersistedEvent

وقتی checkpointهای فایل روی دیسک پایدار می‌شوند صادر می‌شود.

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;
  };
  uuid: UUID;
  session_id: string;
};

SDKLocalCommandOutputMessage

خروجی از یک دستورِ اسلشِ محلی (مثلاً /voice یا /usage). به‌صورتِ متنِ سبکِ‌دستیار در رونوشت نمایش داده می‌شود.

type SDKLocalCommandOutputMessage = {
  type: "system";
  subtype: "local_command_output";
  content: string;
  uuid: UUID;
  session_id: string;
};

SDKCommandsChangedMessage

وقتی مجموعه‌ی دستورهای در دسترس وسطِ نشست تغییر می‌کند صادر می‌شود، مثلاً وقتی skillها همان‌طور که ایجنت واردِ یک زیردایرکتوری می‌شود کشف می‌شوند. آرایه‌ی commands فهرستِ کاملِ به‌روزشده است، پس هر فهرستِ دستورِ کش‌شده را با این محموله جایگزین کن. فراخوانیِ دوباره‌ی supportedCommands() معادل نیست: آن متد snapshotِ گرفته‌شده هنگامِ مقداردهیِ اولیه را برمی‌گرداند و تغییراتِ وسطِ نشست را منعکس نمی‌کند.

type SDKCommandsChangedMessage = {
  type: "system";
  subtype: "commands_changed";
  commands: SlashCommand[];
  uuid: UUID;
  session_id: string;
};

SDKPromptSuggestionMessage

پس از هر نوبت وقتی promptSuggestions فعال باشد صادر می‌شود. شاملِ یک پرامپتِ بعدیِ پیش‌بینی‌شده‌ی کاربر است.

type SDKPromptSuggestionMessage = {
  type: "prompt_suggestion";
  suggestion: string;
  uuid: UUID;
  session_id: string;
};

AbortError

کلاسِ خطای سفارشی برای عملیاتِ لغو.

class AbortError extends Error {}

پیکربندیِ 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;
  ripgrep?: { command: string; args?: string[] };
};

خصوصیت	تایپ	پیش‌فرض	توضیح
enabled	boolean	false	فعال‌کردنِ حالتِ sandbox برای اجرای دستور
failIfUnavailable	boolean	true	اگر enabled برابرِ true باشد اما sandbox نتواند شروع شود، هنگامِ راه‌اندازی متوقف شو. false تنظیم کن تا با یک هشدار روی stderr به اجرای بدونِ‌sandbox برگردد
autoAllowBashIfSandboxed	boolean	true	تأییدِ خودکارِ دستورهای bash وقتی sandbox فعال است
excludedCommands	string[]	[]	دستورهایی که همیشه محدودیت‌های sandbox را دور می‌زنند (مثلاً ['docker']). این‌ها بدونِ دخالتِ مدل به‌صورتِ خودکار بدونِ sandbox اجرا می‌شوند
allowUnsandboxedCommands	boolean	true	به مدل اجازه بده درخواستِ اجرای دستورها خارج از sandbox را بدهد. وقتی true باشد، مدل می‌تواند dangerouslyDisableSandbox را در ورودیِ ابزار تنظیم کند، که به سیستمِ دسترسی‌ها برمی‌گردد
network	SandboxNetworkConfig	undefined	پیکربندیِ sandboxِ مختصِ شبکه
filesystem	SandboxFilesystemConfig	undefined	پیکربندیِ sandboxِ مختصِ فایل‌سیستم برای محدودیت‌های خواندن/نوشتن
ignoreViolations	Record<string, string[]>	undefined	نقشه‌ی دسته‌های نقض به الگوهایی که نادیده گرفته شوند (مثلاً { file: ['/tmp/*'], network: ['localhost'] })
enableWeakerNestedSandbox	boolean	false	فعال‌کردنِ یک sandboxِ تودرتوی ضعیف‌تر برای سازگاری
ripgrep	{ command: string; args?: string[] }	undefined	پیکربندیِ باینریِ ripgrepِ سفارشی برای محیط‌های sandbox

یادداشت

sandbox به پشتیبانیِ پلتفرم و، روی Linux، به ابزارهایی مثلِ bubblewrap و socat بستگی دارد. وقتی enabled برابرِ true باشد و sandbox نتواند شروع شود، query() یک پیامِ result با subtype: "error_during_execution" و دلیل در errors گزارش می‌دهد، سپس متوقف می‌شود. به‌جای انتظارِ این‌که query() پیش از صدورِ پیام‌ها خطا بیندازد، مراقبِ آن subtype باش.

برای اجرای بدونِ‌sandbox به‌جایش failIfUnavailable: false را تنظیم کن.

نمونه‌ی استفاده

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

for await (const message of query({
  prompt: "Build and test my project",
  options: {
    sandbox: {
      enabled: true,
      autoAllowBashIfSandboxed: true,
      network: {
        allowLocalBinding: true
      }
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

احتیاط

امنیتِ سوکتِ Unix: گزینه‌ی allowUnixSockets می‌تواند به سرویس‌های سیستمیِ قدرتمند دسترسی بدهد. مثلاً، اجازه‌دادنِ /var/run/docker.sock عملاً از طریقِ APIِ Docker دسترسیِ کاملِ سیستمِ میزبان را اعطا می‌کند و ایزولاسیونِ sandbox را دور می‌زند. فقط سوکت‌های Unixی را که اکیداً ضروری‌اند اجازه بده و پیامدهای امنیتیِ هرکدام را درک کن.

SandboxNetworkConfig

پیکربندیِ مختصِ شبکه برای حالتِ sandbox. این تنظیمات روی دستورهای Bashِ sandbox‌شده وقتی enabled در SandboxSettingsِ والد برابرِ true باشد اعمال می‌شوند. ابزارِ WebFetch را محدود نمی‌کنند، که به‌جایش از قواعدِ دسترسی استفاده می‌کند.

type SandboxNetworkConfig = {
  allowedDomains?: string[];
  deniedDomains?: string[];
  allowManagedDomainsOnly?: boolean;
  allowLocalBinding?: boolean;
  allowUnixSockets?: string[];
  allowAllUnixSockets?: boolean;
  httpProxyPort?: number;
  socksProxyPort?: number;
};

خصوصیت	تایپ	پیش‌فرض	توضیح
allowedDomains	string[]	[]	نام‌دامنه‌هایی که فرآیندهای sandbox‌شده می‌توانند به آن‌ها دسترسی داشته باشند
deniedDomains	string[]	[]	نام‌دامنه‌هایی که فرآیندهای sandbox‌شده نمی‌توانند به آن‌ها دسترسی داشته باشند. بر allowedDomains تقدم دارد
allowManagedDomainsOnly	boolean	false	فقط managed-settings. وقتی در تنظیماتِ مدیریت‌شده تنظیم شود، فقط ورودی‌های allowedDomains از تنظیماتِ مدیریت‌شده محترم شمرده می‌شوند و ورودی‌های تنظیماتِ کاربر، پروژه یا محلی نادیده گرفته می‌شوند. وقتی از طریقِ گزینه‌های SDK تنظیم شود بی‌اثر است
allowLocalBinding	boolean	false	به فرآیندها اجازه بده به پورت‌های محلی bind کنند (مثلاً برای سرورهای dev)
allowUnixSockets	string[]	[]	مسیرهای سوکتِ Unix که فرآیندها می‌توانند به آن‌ها دسترسی داشته باشند (مثلاً سوکتِ Docker)
allowAllUnixSockets	boolean	false	اجازه‌ی دسترسی به همه‌ی سوکت‌های Unix
httpProxyPort	number	undefined	پورتِ پراکسیِ HTTP برای درخواست‌های شبکه
socksProxyPort	number	undefined	پورتِ پراکسیِ SOCKS برای درخواست‌های شبکه

یادداشت

پراکسیِ sandboxِ توکار، allowedDomains را بر اساسِ hostnameِ درخواست‌شده اعمال می‌کند و ترافیکِ TLS را خاتمه یا بازرسی نمی‌کند، پس تکنیک‌هایی مثلِ domain fronting به‌طورِ بالقوه می‌توانند آن را دور بزنند. برای جزئیات به محدودیت‌های امنیتیِ Sandboxing و برای پیکربندیِ یک پراکسیِ خاتمه‌دهنده‌ی TLS به استقرارِ امن نگاه کن.

SandboxFilesystemConfig

پیکربندیِ مختصِ فایل‌سیستم برای حالتِ sandbox.

type SandboxFilesystemConfig = {
  allowWrite?: string[];
  denyWrite?: string[];
  denyRead?: string[];
};

خصوصیت	تایپ	پیش‌فرض	توضیح
allowWrite	string[]	[]	الگوهای مسیرِ فایل برای اجازه‌ی دسترسیِ نوشتن
denyWrite	string[]	[]	الگوهای مسیرِ فایل برای ردِ دسترسیِ نوشتن
denyRead	string[]	[]	الگوهای مسیرِ فایل برای ردِ دسترسیِ خواندن

بازگشت به سیستمِ دسترسی برای دستورهای بدونِ‌Sandbox

وقتی allowUnsandboxedCommands فعال باشد، مدل می‌تواند با تنظیمِ dangerouslyDisableSandbox: true در ورودیِ ابزار، درخواستِ اجرای دستورها خارج از sandbox را بدهد. این درخواست‌ها به سیستمِ دسترسیِ موجود برمی‌گردند، یعنی هندلرِ canUseToolِ تو فراخوانی می‌شود و به تو امکانِ پیاده‌سازیِ منطقِ مجوزدهیِ سفارشی را می‌دهد.

یادداشت

excludedCommands در برابرِ allowUnsandboxedCommands:

• excludedCommands: یک فهرستِ ایستا از دستورهایی که همیشه به‌صورتِ خودکار sandbox را دور می‌زنند (مثلاً ['docker']). مدل کنترلی روی این ندارد.
• allowUnsandboxedCommands: به مدل اجازه می‌دهد در زمانِ اجرا تصمیم بگیرد آیا با تنظیمِ dangerouslyDisableSandbox: true در ورودیِ ابزار، درخواستِ اجرای بدونِ‌sandbox بدهد.

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

for await (const message of query({
  prompt: "Deploy my application",
  options: {
    sandbox: {
      enabled: true,
      allowUnsandboxedCommands: true // Model can request unsandboxed execution
    },
    permissionMode: "default",
    canUseTool: async (tool, input) => {
      // Check if the model is requesting to bypass the sandbox
      if (tool === "Bash" && input.dangerouslyDisableSandbox) {
        // The model is requesting to run this command outside the sandbox
        console.log(`Unsandboxed command requested: ${input.command}`);

        if (isCommandAuthorized(input.command)) {
          return { behavior: "allow" as const, updatedInput: input };
        }
        return {
          behavior: "deny" as const,
          message: "Command not authorized for unsandboxed execution"
        };
      }
      return { behavior: "allow" as const, updatedInput: input };
    }
  }
})) {
  if ("result" in message) console.log(message.result);
}

این الگو به تو امکان می‌دهد:

• درخواست‌های مدل را ممیزی کنی: وقتی مدل درخواستِ اجرای بدونِ‌sandbox می‌دهد لاگ بگیری
• allowlist پیاده‌سازی کنی: فقط به دستورهای خاص اجازه بدهی بدونِ sandbox اجرا شوند
• جریان‌های تأیید اضافه کنی: برای عملیاتِ ممتاز مجوزِ صریح بطلبی

احتیاط

دستورهایی که با dangerouslyDisableSandbox: true اجرا می‌شوند دسترسیِ کاملِ سیستم دارند. مطمئن شو هندلرِ canUseToolت این درخواست‌ها را با دقت اعتبارسنجی می‌کند.

اگر permissionMode روی bypassPermissions تنظیم شده باشد و allowUnsandboxedCommands فعال باشد، مدل می‌تواند خودمختار دستورها را خارج از sandbox بدونِ پرسش‌های تأیید اجرا کند (یک قاعده‌ی askِ صریح همچنان یکی را اجبار می‌کند). این ترکیب عملاً به مدل اجازه می‌دهد بی‌سروصدا از ایزولاسیونِ sandbox فرار کند.

همچنین ببینید

• مرورِ کلیِ SDK - مفاهیمِ عمومیِ SDK
• مرجعِ Python SDK - مستنداتِ Python SDK
• مرجعِ CLI - رابطِ خطِ‌فرمان
• ورک‌فلوهای رایج - راهنماهای گام‌به‌گام