Agent SDK reference - TypeScript

Coba antarmuka V2 baru (pratinjau): Antarmuka yang disederhanakan dengan pola send() dan stream() kini tersedia, membuat percakapan multi-putaran lebih mudah. Pelajari lebih lanjut tentang pratinjau TypeScript V2

Instalasi

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

SDK menggabungkan biner Claude Code asli untuk platform Anda sebagai dependensi opsional seperti @anthropic-ai/claude-agent-sdk-darwin-arm64. Anda tidak perlu menginstal Claude Code secara terpisah. Jika pengelola paket Anda melewatkan dependensi opsional, SDK melempar Native CLI binary for <platform> not found; setel pathToClaudeCodeExecutable ke biner claude yang diinstal secara terpisah sebagai gantinya.

Fungsi

`query()`

Fungsi utama untuk berinteraksi dengan Claude Code. Membuat generator asinkron yang melakukan streaming pesan saat tiba.

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

Parameter

Parameter	Tipe	Deskripsi
`prompt`	`string \| AsyncIterable<SDKUserMessage>`	Prompt input sebagai string atau async iterable untuk mode streaming
`options`	`Options`	Objek konfigurasi opsional (lihat tipe Options di bawah)

Pengembalian

Mengembalikan objek Query yang memperluas AsyncGenerator<SDKMessage, void> dengan metode tambahan.

`startup()`

Pra-pemanasan subprocess CLI dengan menspawnya dan menyelesaikan handshake inisialisasi sebelum prompt tersedia. Handle WarmQuery yang dikembalikan menerima prompt nanti dan menulisnya ke proses yang sudah siap, sehingga panggilan query() pertama diselesaikan tanpa membayar biaya spawn dan inisialisasi subprocess secara inline.

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

Parameter

Parameter	Tipe	Deskripsi
`options`	`Options`	Objek konfigurasi opsional. Sama dengan parameter `options` ke `query()`
`initializeTimeoutMs`	`number`	Waktu maksimum dalam milidetik untuk menunggu inisialisasi subprocess. Default ke `60000`. Jika inisialisasi tidak selesai tepat waktu, promise ditolak dengan error timeout

Pengembalian

Mengembalikan Promise<WarmQuery> yang diselesaikan setelah subprocess telah dispawn dan menyelesaikan handshake inisialisasinya.

Contoh

Panggil startup() lebih awal, misalnya saat boot aplikasi, kemudian panggil .query() pada handle yang dikembalikan setelah prompt siap. Ini memindahkan spawn subprocess dan inisialisasi keluar dari jalur kritis.

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

// Bayar biaya startup di muka
const warm = await startup({ options: { maxTurns: 3 } });

// Nanti, ketika prompt siap, ini langsung
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

`tool()`

Membuat definisi tool MCP yang aman tipe untuk digunakan dengan server 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>;

Parameter

Parameter	Tipe	Deskripsi
`name`	`string`	Nama tool
`description`	`string`	Deskripsi tentang apa yang dilakukan tool
`inputSchema`	`Schema extends AnyZodRawShape`	Skema Zod yang mendefinisikan parameter input tool (mendukung Zod 3 dan Zod 4)
`handler`	`(args, extra) => Promise<CallToolResult>`	Fungsi asinkron yang mengeksekusi logika tool
`extras`	`{ annotations?:` `ToolAnnotations` `}`	Anotasi tool MCP opsional yang memberikan petunjuk perilaku kepada klien

`ToolAnnotations`

Dieksport ulang dari @modelcontextprotocol/sdk/types.js. Semua field adalah petunjuk opsional; klien tidak boleh mengandalkannya untuk keputusan keamanan.

Field	Tipe	Default	Deskripsi
`title`	`string`	`undefined`	Judul yang dapat dibaca manusia untuk tool
`readOnlyHint`	`boolean`	`false`	Jika `true`, tool tidak memodifikasi lingkungannya
`destructiveHint`	`boolean`	`true`	Jika `true`, tool dapat melakukan pembaruan destruktif (hanya bermakna ketika `readOnlyHint` adalah `false`)
`idempotentHint`	`boolean`	`false`	Jika `true`, panggilan berulang dengan argumen yang sama tidak memiliki efek tambahan (hanya bermakna ketika `readOnlyHint` adalah `false`)
`openWorldHint`	`boolean`	`true`	Jika `true`, tool berinteraksi dengan entitas eksternal (misalnya, pencarian web). Jika `false`, domain tool ditutup (misalnya, tool memori)

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

Membuat instance server MCP yang berjalan dalam proses yang sama dengan aplikasi Anda.

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

Parameter

Parameter	Tipe	Deskripsi
`options.name`	`string`	Nama server MCP
`options.version`	`string`	String versi opsional
`options.tools`	`Array<SdkMcpToolDefinition>`	Array definisi tool yang dibuat dengan `tool()`

`listSessions()`

Menemukan dan membuat daftar sesi masa lalu dengan metadata ringan. Filter berdasarkan direktori proyek atau buat daftar sesi di semua proyek.

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

Parameter

Parameter	Tipe	Default	Deskripsi
`options.dir`	`string`	`undefined`	Direktori untuk membuat daftar sesi. Ketika dihilangkan, mengembalikan sesi di semua proyek
`options.limit`	`number`	`undefined`	Jumlah maksimum sesi yang akan dikembalikan
`options.includeWorktrees`	`boolean`	`true`	Ketika `dir` berada di dalam repositori git, sertakan sesi dari semua jalur worktree

Tipe pengembalian: `SDKSessionInfo`

Properti	Tipe	Deskripsi
`sessionId`	`string`	Pengenal sesi unik (UUID)
`summary`	`string`	Judul tampilan: judul kustom, ringkasan yang dihasilkan otomatis, atau prompt pertama
`lastModified`	`number`	Waktu modifikasi terakhir dalam milidetik sejak epoch
`fileSize`	`number \| undefined`	Ukuran file sesi dalam byte. Hanya diisi untuk penyimpanan JSONL lokal
`customTitle`	`string \| undefined`	Judul sesi yang ditetapkan pengguna (melalui `/rename`)
`firstPrompt`	`string \| undefined`	Prompt pengguna bermakna pertama dalam sesi
`gitBranch`	`string \| undefined`	Cabang Git di akhir sesi
`cwd`	`string \| undefined`	Direktori kerja untuk sesi
`tag`	`string \| undefined`	Tag sesi yang ditetapkan pengguna (lihat `tagSession()`)
`createdAt`	`number \| undefined`	Waktu pembuatan dalam milidetik sejak epoch, dari timestamp entri pertama

Contoh

Cetak 10 sesi terbaru untuk proyek. Hasil diurutkan berdasarkan lastModified menurun, jadi item pertama adalah yang terbaru. Hilangkan dir untuk mencari di semua proyek.

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

Membaca pesan pengguna dan asisten dari transkrip sesi masa lalu.

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

Parameter

Parameter	Tipe	Default	Deskripsi
`sessionId`	`string`	required	UUID sesi untuk dibaca (lihat `listSessions()`)
`options.dir`	`string`	`undefined`	Direktori proyek untuk menemukan sesi. Ketika dihilangkan, mencari di semua proyek
`options.limit`	`number`	`undefined`	Jumlah maksimum pesan yang akan dikembalikan
`options.offset`	`number`	`undefined`	Jumlah pesan yang akan dilewati dari awal

Tipe pengembalian: `SessionMessage`

Properti	Tipe	Deskripsi
`type`	`"user" \| "assistant"`	Peran pesan
`uuid`	`string`	Pengenal pesan unik
`session_id`	`string`	Sesi yang pesan ini milik
`message`	`unknown`	Payload pesan mentah dari transkrip
`parent_tool_use_id`	`null`	Dicadangkan

Contoh

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

Membaca metadata untuk sesi tunggal berdasarkan ID tanpa memindai direktori proyek lengkap.

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

Parameter

Parameter	Tipe	Default	Deskripsi
`sessionId`	`string`	required	UUID sesi yang akan dicari
`options.dir`	`string`	`undefined`	Jalur direktori proyek. Ketika dihilangkan, mencari di semua direktori proyek

Mengembalikan SDKSessionInfo, atau undefined jika sesi tidak ditemukan.

`renameSession()`

Mengganti nama sesi dengan menambahkan entri judul kustom. Panggilan berulang aman; judul terbaru menang.

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

Parameter

Parameter	Tipe	Default	Deskripsi
`sessionId`	`string`	required	UUID sesi yang akan diganti nama
`title`	`string`	required	Judul baru. Harus tidak kosong setelah memangkas spasi putih
`options.dir`	`string`	`undefined`	Jalur direktori proyek. Ketika dihilangkan, mencari di semua direktori proyek

`tagSession()`

Menandai sesi. Lewatkan null untuk menghapus tag. Panggilan berulang aman; tag terbaru menang.

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

Parameter

Parameter	Tipe	Default	Deskripsi
`sessionId`	`string`	required	UUID sesi yang akan ditandai
`tag`	`string \| null`	required	String tag, atau `null` untuk menghapus
`options.dir`	`string`	`undefined`	Jalur direktori proyek. Ketika dihilangkan, mencari di semua direktori proyek

Tipe

`Options`

Objek konfigurasi untuk fungsi query().

Properti	Tipe	Default	Deskripsi
`abortController`	`AbortController`	`new AbortController()`	Pengontrol untuk membatalkan operasi
`additionalDirectories`	`string[]`	`[]`	Direktori tambahan yang dapat diakses Claude
`agent`	`string`	`undefined`	Nama agen untuk thread utama. Agen harus didefinisikan dalam opsi `agents` atau dalam pengaturan
`agents`	`Record<string, [`AgentDefinition`](#agent-definition)>`	`undefined`	Tentukan subagen secara terprogram
`allowDangerouslySkipPermissions`	`boolean`	`false`	Aktifkan bypass izin. Diperlukan saat menggunakan `permissionMode: 'bypassPermissions'`
`allowedTools`	`string[]`	`[]`	Tool untuk auto-approve tanpa prompt. Ini tidak membatasi Claude hanya pada tool ini; tool yang tidak terdaftar jatuh ke `permissionMode` dan `canUseTool`. Gunakan `disallowedTools` untuk memblokir tool. Lihat Izin
`betas`	`SdkBeta[]`	`[]`	Aktifkan fitur beta
`canUseTool`	`CanUseTool`	`undefined`	Fungsi izin kustom untuk penggunaan tool
`continue`	`boolean`	`false`	Lanjutkan percakapan terbaru
`cwd`	`string`	`process.cwd()`	Direktori kerja saat ini
`debug`	`boolean`	`false`	Aktifkan mode debug untuk proses Claude Code
`debugFile`	`string`	`undefined`	Tulis log debug ke jalur file tertentu. Secara implisit mengaktifkan mode debug
`disallowedTools`	`string[]`	`[]`	Tool untuk selalu tolak. Aturan tolak diperiksa terlebih dahulu dan mengganti `allowedTools` dan `permissionMode` (termasuk `bypassPermissions`)
`effort`	`'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'`	`'high'`	Mengontrol seberapa banyak usaha yang Claude masukkan ke dalam responsnya. Bekerja dengan pemikiran adaptif untuk memandu kedalaman pemikiran
`enableFileCheckpointing`	`boolean`	`false`	Aktifkan pelacakan perubahan file untuk rewinding. Lihat File checkpointing
`env`	`Record<string, string \| undefined>`	`process.env`	Variabel lingkungan. Atur `CLAUDE_AGENT_SDK_CLIENT_APP` untuk mengidentifikasi aplikasi Anda di header User-Agent
`executable`	`'bun' \| 'deno' \| 'node'`	Auto-detected	Runtime JavaScript yang akan digunakan
`executableArgs`	`string[]`	`[]`	Argumen untuk diteruskan ke executable
`extraArgs`	`Record<string, string \| null>`	`{}`	Argumen tambahan
`fallbackModel`	`string`	`undefined`	Model yang digunakan jika model utama gagal
`forkSession`	`boolean`	`false`	Saat melanjutkan dengan `resume`, fork ke ID sesi baru alih-alih melanjutkan sesi asli
`hooks`	`Partial<Record<HookEvent,` `HookCallbackMatcher[]>>`	`{}`	Callback hook untuk event
`includePartialMessages`	`boolean`	`false`	Sertakan event pesan parsial
`maxBudgetUsd`	`number`	`undefined`	Hentikan query ketika estimasi biaya sisi klien mencapai nilai USD ini. Dibandingkan dengan estimasi yang sama seperti `total_cost_usd`; lihat Lacak biaya dan penggunaan untuk peringatan akurasi
`maxThinkingTokens`	`number`	`undefined`	Deprecated: Gunakan opsi `thinking` sebagai gantinya. Token maksimum untuk proses pemikiran
`maxTurns`	`number`	`undefined`	Putaran agen maksimum (perjalanan round-trip penggunaan tool)
`mcpServers`	`Record<string, [`McpServerConfig`](#mcp-server-config)>`	`{}`	Konfigurasi server MCP
`model`	`string`	Default dari CLI	Model Claude yang akan digunakan
`outputFormat`	`{ type: 'json_schema', schema: JSONSchema }`	`undefined`	Tentukan format output untuk hasil agen. Lihat Output terstruktur untuk detail
`pathToClaudeCodeExecutable`	`string`	Auto-resolved dari biner asli bundel	Jalur ke executable Claude Code. Hanya diperlukan jika dependensi opsional dilewati selama instalasi atau platform Anda tidak dalam set yang didukung
`permissionMode`	`PermissionMode`	`'default'`	Mode izin untuk sesi
`permissionPromptToolName`	`string`	`undefined`	Nama tool MCP untuk prompt izin
`persistSession`	`boolean`	`true`	Ketika `false`, menonaktifkan persistensi sesi ke disk. Sesi tidak dapat dilanjutkan nanti
`plugins`	`SdkPluginConfig[]`	`[]`	Muat plugin kustom dari jalur lokal. Lihat Plugins untuk detail
`promptSuggestions`	`boolean`	`false`	Aktifkan saran prompt. Mengirimkan pesan `prompt_suggestion` setelah setiap putaran dengan prompt pengguna berikutnya yang diprediksi
`resume`	`string`	`undefined`	ID sesi untuk dilanjutkan
`resumeSessionAt`	`string`	`undefined`	Lanjutkan sesi pada UUID pesan tertentu
`sandbox`	`SandboxSettings`	`undefined`	Konfigurasi perilaku sandbox secara terprogram. Lihat Pengaturan sandbox untuk detail
`sessionId`	`string`	Auto-generated	Gunakan UUID tertentu untuk sesi alih-alih auto-generate
`settingSources`	`SettingSource[]`	CLI defaults (all sources)	Kontrol pengaturan filesystem mana yang akan dimuat. Lewatkan `[]` untuk menonaktifkan pengaturan pengguna, proyek, dan lokal. Pengaturan kebijakan terkelola dimuat terlepas dari itu. Lihat Gunakan fitur Claude Code
`spawnClaudeCodeProcess`	`(options: SpawnOptions) => SpawnedProcess`	`undefined`	Fungsi kustom untuk spawn proses Claude Code. Gunakan untuk menjalankan Claude Code di VM, kontainer, atau lingkungan jarak jauh
`stderr`	`(data: string) => void`	`undefined`	Callback untuk output stderr
`strictMcpConfig`	`boolean`	`false`	Terapkan validasi MCP ketat
`systemPrompt`	`string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }`	`undefined` (minimal prompt)	Konfigurasi prompt sistem. Lewatkan string untuk prompt kustom, atau `{ type: 'preset', preset: 'claude_code' }` untuk menggunakan prompt sistem Claude Code. Saat menggunakan bentuk objek preset, tambahkan `append` untuk memperluas dengan instruksi tambahan, dan atur `excludeDynamicSections: true` untuk memindahkan konteks per-sesi ke pesan pengguna pertama untuk reuse prompt-cache yang lebih baik di seluruh mesin
`thinking`	`ThinkingConfig`	`{ type: 'adaptive' }` untuk model yang didukung	Mengontrol perilaku pemikiran/penalaran Claude. Lihat `ThinkingConfig` untuk opsi
`toolConfig`	`ToolConfig`	`undefined`	Konfigurasi untuk perilaku tool bawaan. Lihat `ToolConfig` untuk detail
`tools`	`string[] \| { type: 'preset'; preset: 'claude_code' }`	`undefined`	Konfigurasi tool. Lewatkan array nama tool atau gunakan preset untuk mendapatkan tool default Claude Code

Objek `Query`

Antarmuka yang dikembalikan oleh fungsi 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>;
  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;
}

Metode

Metode	Deskripsi
`interrupt()`	Mengganggu query (hanya tersedia dalam mode input streaming)
`rewindFiles(userMessageId, options?)`	Mengembalikan file ke keadaan mereka pada pesan pengguna yang ditentukan. Lewatkan `{ dryRun: true }` untuk pratinjau perubahan. Memerlukan `enableFileCheckpointing: true`. Lihat File checkpointing
`setPermissionMode()`	Mengubah mode izin (hanya tersedia dalam mode input streaming)
`setModel()`	Mengubah model (hanya tersedia dalam mode input streaming)
`setMaxThinkingTokens()`	Deprecated: Gunakan opsi `thinking` sebagai gantinya. Mengubah token pemikiran maksimum
`initializationResult()`	Mengembalikan hasil inisialisasi lengkap termasuk perintah yang didukung, model, info akun, dan konfigurasi gaya output
`supportedCommands()`	Mengembalikan perintah slash yang tersedia
`supportedModels()`	Mengembalikan model yang tersedia dengan info tampilan
`supportedAgents()`	Mengembalikan subagen yang tersedia sebagai `AgentInfo[]`
`mcpServerStatus()`	Mengembalikan status server MCP yang terhubung
`accountInfo()`	Mengembalikan informasi akun
`reconnectMcpServer(serverName)`	Sambungkan kembali server MCP berdasarkan nama
`toggleMcpServer(serverName, enabled)`	Aktifkan atau nonaktifkan server MCP berdasarkan nama
`setMcpServers(servers)`	Ganti secara dinamis set server MCP untuk sesi ini. Mengembalikan info tentang server mana yang ditambahkan, dihapus, dan error apa pun
`streamInput(stream)`	Alirkan pesan input ke query untuk percakapan multi-putaran
`stopTask(taskId)`	Hentikan tugas latar belakang yang sedang berjalan berdasarkan ID
`close()`	Tutup query dan hentikan proses yang mendasarinya. Secara paksa mengakhiri query dan membersihkan semua sumber daya

`WarmQuery`

Handle yang dikembalikan oleh startup(). Subprocess sudah dispawn dan diinisialisasi, jadi memanggil query() pada handle ini menulis prompt langsung ke proses yang siap tanpa latensi startup.

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

Metode

Metode	Deskripsi
`query(prompt)`	Kirim prompt ke subprocess yang sudah dipanaskan dan kembalikan `Query`. Hanya dapat dipanggil sekali per `WarmQuery`
`close()`	Tutup subprocess tanpa mengirim prompt. Gunakan ini untuk membuang warm query yang tidak lagi diperlukan

WarmQuery mengimplementasikan AsyncDisposable, jadi dapat digunakan dengan await using untuk pembersihan otomatis.

`SDKControlInitializeResponse`

Tipe pengembalian dari initializationResult(). Berisi data inisialisasi sesi.

type SDKControlInitializeResponse = {
  commands: SlashCommand[];
  agents: AgentInfo[];
  output_style: string;
  available_output_styles: string[];
  models: ModelInfo[];
  account: AccountInfo;
  fast_mode_state?: "off" | "cooldown" | "on";
};

`AgentDefinition`

Konfigurasi untuk subagen yang didefinisikan secara terprogram.

type AgentDefinition = {
  description: string;
  tools?: string[];
  disallowedTools?: string[];
  prompt: string;
  model?: "sonnet" | "opus" | "haiku" | "inherit";
  mcpServers?: AgentMcpServerSpec[];
  skills?: string[];
  maxTurns?: number;
  criticalSystemReminder_EXPERIMENTAL?: string;
};

Field	Diperlukan	Deskripsi
`description`	Ya	Deskripsi bahasa alami tentang kapan menggunakan agen ini
`tools`	Tidak	Array nama tool yang diizinkan. Jika dihilangkan, mewarisi semua tool dari parent
`disallowedTools`	Tidak	Array nama tool untuk secara eksplisit tidak izinkan untuk agen ini
`prompt`	Ya	Prompt sistem agen
`model`	Tidak	Penggantian model untuk agen ini. Jika dihilangkan atau `'inherit'`, menggunakan model utama
`mcpServers`	Tidak	Spesifikasi server MCP untuk agen ini
`skills`	Tidak	Array nama skill untuk preload ke konteks agen
`maxTurns`	Tidak	Jumlah maksimum putaran agen (API round-trips) sebelum berhenti
`criticalSystemReminder_EXPERIMENTAL`	Tidak	Eksperimental: Pengingat kritis ditambahkan ke prompt sistem

`AgentMcpServerSpec`

Menentukan server MCP yang tersedia untuk subagen. Dapat berupa nama server (string yang mereferensikan server dari konfigurasi mcpServers parent) atau konfigurasi server inline yang merekam nama server ke config.

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

Di mana McpServerConfigForProcessTransport adalah McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig.

`SettingSource`

Mengontrol sumber konfigurasi berbasis filesystem mana yang dimuat pengaturan SDK.

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

Nilai	Deskripsi	Lokasi
`'user'`	Pengaturan pengguna global	`~/.claude/settings.json`
`'project'`	Pengaturan proyek bersama (version controlled)	`.claude/settings.json`
`'local'`	Pengaturan proyek lokal (gitignored)	`.claude/settings.local.json`

Perilaku default

Ketika settingSources dihilangkan atau undefined, query() memuat pengaturan filesystem yang sama seperti CLI Claude Code: pengguna, proyek, dan lokal. Pengaturan kebijakan terkelola dimuat dalam semua kasus. Lihat Apa yang tidak dikontrol settingSources untuk input yang dibaca terlepas dari opsi ini, dan cara menonaktifkannya.

Mengapa menggunakan settingSources

Nonaktifkan pengaturan filesystem:

// Jangan muat pengaturan pengguna, proyek, atau lokal dari disk
const result = query({
  prompt: "Analyze this code",
  options: { settingSources: [] }
});

Muat semua pengaturan filesystem secara eksplisit:

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

Muat hanya sumber pengaturan tertentu:

// Muat hanya pengaturan proyek, abaikan pengguna dan lokal
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ["project"] // Hanya .claude/settings.json
  }
});

Lingkungan pengujian dan CI:

// Pastikan perilaku konsisten di CI dengan mengecualikan pengaturan lokal
const result = query({
  prompt: "Run tests",
  options: {
    settingSources: ["project"], // Hanya pengaturan bersama tim
    permissionMode: "bypassPermissions"
  }
});

Aplikasi SDK-only:

// Tentukan semuanya secara terprogram.
// Lewatkan [] untuk opt out dari sumber pengaturan filesystem.
const result = query({
  prompt: "Review this PR",
  options: {
    settingSources: [],
    agents: {
      /* ... */
    },
    mcpServers: {
      /* ... */
    },
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

Memuat instruksi proyek CLAUDE.md:

// Muat pengaturan proyek untuk menyertakan file CLAUDE.md
const result = query({
  prompt: "Add a new feature following project conventions",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // Gunakan prompt sistem Claude Code
    },
    settingSources: ["project"], // Memuat CLAUDE.md dari direktori proyek
    allowedTools: ["Read", "Write", "Edit"]
  }
});

Preseden pengaturan

Ketika beberapa sumber dimuat, pengaturan digabungkan dengan preseden ini (tertinggi ke terendah):

Pengaturan lokal (.claude/settings.local.json)
Pengaturan proyek (.claude/settings.json)
Pengaturan pengguna (~/.claude/settings.json)

Opsi terprogram seperti agents dan allowedTools mengganti pengaturan filesystem pengguna, proyek, dan lokal. Pengaturan kebijakan terkelola mengambil preseden atas opsi terprogram.

`PermissionMode`

type PermissionMode =
  | "default" // Perilaku izin standar
  | "acceptEdits" // Auto-accept edit file
  | "bypassPermissions" // Bypass semua pemeriksaan izin
  | "plan" // Mode perencanaan - tidak ada eksekusi
  | "dontAsk" // Jangan prompt untuk izin, tolak jika tidak pre-approved
  | "auto"; // Gunakan classifier model untuk approve atau deny setiap tool call

`CanUseTool`

Tipe fungsi izin kustom untuk mengontrol penggunaan tool.

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

Opsi	Tipe	Deskripsi
`signal`	`AbortSignal`	Signaled jika operasi harus dibatalkan
`suggestions`	`PermissionUpdate[]`	Saran pembaruan izin sehingga pengguna tidak diprompt lagi untuk tool ini
`blockedPath`	`string`	Jalur file yang memicu permintaan izin, jika berlaku
`decisionReason`	`string`	Menjelaskan mengapa permintaan izin ini dipicu
`toolUseID`	`string`	Pengenal unik untuk tool call spesifik ini dalam pesan asisten
`agentID`	`string`	Jika berjalan dalam sub-agen, ID sub-agen

`PermissionResult`

Hasil pemeriksaan izin.

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

`ToolConfig`

Konfigurasi untuk perilaku tool bawaan.

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

Field	Tipe	Deskripsi
`askUserQuestion.previewFormat`	`'markdown' \| 'html'`	Opt-in ke field `preview` pada opsi `AskUserQuestion` dan atur format kontennya. Ketika tidak diatur, Claude tidak mengirimkan preview

`McpServerConfig`

Konfigurasi untuk server 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`

Konfigurasi untuk memuat plugin di SDK.

type SdkPluginConfig = {
  type: "local";
  path: string;
};

Field	Tipe	Deskripsi
`type`	`'local'`	Harus `'local'` (hanya plugin lokal yang saat ini didukung)
`path`	`string`	Jalur absolut atau relatif ke direktori plugin

Contoh:

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

Untuk informasi lengkap tentang membuat dan menggunakan plugin, lihat Plugins.

Tipe Pesan

`SDKMessage`

Tipe union dari semua pesan yang mungkin dikembalikan oleh query.

type SDKMessage =
  | SDKAssistantMessage
  | SDKUserMessage
  | SDKUserMessageReplay
  | SDKResultMessage
  | SDKSystemMessage
  | SDKPartialAssistantMessage
  | SDKCompactBoundaryMessage
  | SDKStatusMessage
  | SDKLocalCommandOutputMessage
  | SDKHookStartedMessage
  | SDKHookProgressMessage
  | SDKHookResponseMessage
  | SDKPluginInstallMessage
  | SDKToolProgressMessage
  | SDKAuthStatusMessage
  | SDKTaskNotificationMessage
  | SDKTaskStartedMessage
  | SDKTaskProgressMessage
  | SDKFilesPersistedEvent
  | SDKToolUseSummaryMessage
  | SDKRateLimitEvent
  | SDKPromptSuggestionMessage;

`SDKAssistantMessage`

Pesan respons asisten.

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

Field message adalah BetaMessage dari Anthropic SDK. Ini mencakup field seperti id, content, model, stop_reason, dan usage. SDKAssistantMessageError adalah salah satu dari: 'authentication_failed', 'billing_error', 'rate_limit', 'invalid_request', 'server_error', 'max_output_tokens', atau 'unknown'.

`SDKUserMessage`

Pesan input pengguna.

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

Atur shouldQuery ke false untuk menambahkan pesan ke transkrip tanpa memicu putaran asisten. Pesan ditahan dan digabungkan ke pesan pengguna berikutnya yang memicu putaran. Gunakan ini untuk menyuntikkan konteks, seperti output perintah yang Anda jalankan out of band, tanpa menghabiskan panggilan model.

`SDKUserMessageReplay`

Pesan pengguna yang diputar ulang dengan UUID yang diperlukan.

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

`SDKResultMessage`

Pesan hasil akhir.

type SDKResultMessage =
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      result: string;
      stop_reason: string | null;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      structured_output?: unknown;
    }
  | {
      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[];
    };

`SDKSystemMessage`

Pesan inisialisasi sistem.

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`

Pesan parsial streaming (hanya ketika includePartialMessages adalah true).

type SDKPartialAssistantMessage = {
  type: "stream_event";
  event: BetaRawMessageStreamEvent; // Dari Anthropic SDK
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
};

`SDKCompactBoundaryMessage`

Pesan yang menunjukkan batas pemadatan percakapan.

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

`SDKPluginInstallMessage`

Event kemajuan instalasi plugin. Dipancarkan ketika CLAUDE_CODE_SYNC_PLUGIN_INSTALL diatur, sehingga aplikasi Agent SDK Anda dapat melacak instalasi plugin marketplace sebelum putaran pertama. Status started dan completed membatasi keseluruhan instalasi. Status installed dan failed melaporkan marketplace individual dan menyertakan name.

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

`SDKPermissionDenial`

Informasi tentang penggunaan tool yang ditolak.

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

Tipe Hook

Untuk panduan komprehensif tentang menggunakan hook dengan contoh dan pola umum, lihat panduan Hooks.

`HookEvent`

Event hook yang tersedia.

type HookEvent =
  | "PreToolUse"
  | "PostToolUse"
  | "PostToolUseFailure"
  | "Notification"
  | "UserPromptSubmit"
  | "SessionStart"
  | "SessionEnd"
  | "Stop"
  | "SubagentStart"
  | "SubagentStop"
  | "PreCompact"
  | "PermissionRequest"
  | "Setup"
  | "TeammateIdle"
  | "TaskCompleted"
  | "ConfigChange"
  | "WorktreeCreate"
  | "WorktreeRemove";

`HookCallback`

Tipe fungsi callback hook.

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

`HookCallbackMatcher`

Konfigurasi hook dengan matcher opsional.

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
  timeout?: number; // Timeout dalam detik untuk semua hook dalam matcher ini
}

`HookInput`

Tipe union dari semua tipe input hook.

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

`BaseHookInput`

Antarmuka dasar yang diperluas oleh semua tipe input hook.

type BaseHookInput = {
  session_id: string;
  transcript_path: string;
  cwd: string;
  permission_mode?: 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;
};

`PostToolUseFailureHookInput`

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

`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 dari array EXIT_REASONS
};

`StopHookInput`

type StopHookInput = BaseHookInput & {
  hook_event_name: "Stop";
  stop_hook_active: boolean;
  last_assistant_message?: string;
};

`SubagentStartHookInput`

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

`SubagentStopHookInput`

type SubagentStopHookInput = BaseHookInput & {
  hook_event_name: "SubagentStop";
  stop_hook_active: boolean;
  agent_id: string;
  agent_transcript_path: string;
  agent_type: string;
  last_assistant_message?: string;
};

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

`HookJSONOutput`

Nilai pengembalian 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";
        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;
        updatedMCPToolOutput?: unknown;
      }
    | {
        hookEventName: "PostToolUseFailure";
        additionalContext?: string;
      }
    | {
        hookEventName: "Notification";
        additionalContext?: string;
      }
    | {
        hookEventName: "PermissionRequest";
        decision:
          | {
              behavior: "allow";
              updatedInput?: Record<string, unknown>;
              updatedPermissions?: PermissionUpdate[];
            }
          | {
              behavior: "deny";
              message?: string;
              interrupt?: boolean;
            };
      };
};

Tipe Input Tool

Dokumentasi skema input untuk semua tool Claude Code bawaan. Tipe ini dieksport dari @anthropic-ai/claude-agent-sdk dan dapat digunakan untuk interaksi tool yang aman tipe.

`ToolInputSchemas`

Union dari semua tipe input tool, dieksport dari @anthropic-ai/claude-agent-sdk.

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

Agent

Nama tool: Agent (sebelumnya Task, yang masih diterima sebagai alias)

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

Meluncurkan agen baru untuk menangani tugas kompleks multi-langkah secara otonom.

AskUserQuestion

Nama tool: AskUserQuestion

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

Menanyakan pertanyaan klarifikasi kepada pengguna selama eksekusi. Lihat Tangani persetujuan dan input pengguna untuk detail penggunaan.

Bash

Nama tool: Bash

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

Mengeksekusi perintah bash dalam sesi shell persisten dengan timeout opsional dan eksekusi latar belakang.

Monitor

Nama tool: Monitor

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

Menjalankan skrip latar belakang dan mengirimkan setiap baris stdout ke Claude sebagai event sehingga dapat bereaksi tanpa polling. Atur persistent: true untuk watch panjang sesi seperti log tails. Monitor mengikuti aturan izin yang sama seperti Bash. Lihat referensi tool Monitor untuk perilaku dan ketersediaan provider.

TaskOutput

Nama tool: TaskOutput

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

Mengambil output dari tugas latar belakang yang sedang berjalan atau selesai.

Edit

Nama tool: Edit

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

Melakukan penggantian string yang tepat dalam file.

Read

Nama tool: Read

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

Membaca file dari filesystem lokal, termasuk teks, gambar, PDF, dan notebook Jupyter. Gunakan pages untuk rentang halaman PDF (misalnya, "1-5").

Write

Nama tool: Write

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

Menulis file ke filesystem lokal, menimpa jika ada.

Glob

Nama tool: Glob

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

Pencocokan pola file cepat yang bekerja dengan ukuran codebase apa pun.

Grep

Nama tool: 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;
};

Tool pencarian yang kuat dibangun di atas ripgrep dengan dukungan regex.

TaskStop

Nama tool: TaskStop

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

Menghentikan tugas latar belakang atau shell yang sedang berjalan berdasarkan ID.

NotebookEdit

Nama tool: NotebookEdit

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

Mengedit sel dalam file notebook Jupyter.

WebFetch

Nama tool: WebFetch

type WebFetchInput = {
  url: string;
  prompt: string;
};

Mengambil konten dari URL dan memprosesnya dengan model AI.

WebSearch

Nama tool: WebSearch

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

Mencari web dan mengembalikan hasil yang diformat.

TodoWrite

Nama tool: TodoWrite

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

Membuat dan mengelola daftar tugas terstruktur untuk melacak kemajuan.

ExitPlanMode

Nama tool: ExitPlanMode

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

Keluar dari mode perencanaan. Secara opsional menentukan izin berbasis prompt yang diperlukan untuk mengimplementasikan rencana.

ListMcpResources

Nama tool: ListMcpResources

type ListMcpResourcesInput = {
  server?: string;
};

Membuat daftar sumber daya MCP yang tersedia dari server yang terhubung.

ReadMcpResource

Nama tool: ReadMcpResource

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

Membaca sumber daya MCP tertentu dari server.

Config

Nama tool: Config

type ConfigInput = {
  setting: string;
  value?: string | boolean | number;
};

Mendapatkan atau menetapkan nilai konfigurasi.

EnterWorktree

Nama tool: EnterWorktree

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

Membuat dan memasuki worktree git sementara untuk pekerjaan terisolasi. Lewatkan path untuk beralih ke worktree yang ada dari repositori saat ini alih-alih membuat yang baru. name dan path saling eksklusif.

Tipe Output Tool

Dokumentasi skema output untuk semua tool Claude Code bawaan. Tipe ini dieksport dari @anthropic-ai/claude-agent-sdk dan mewakili data respons aktual yang dikembalikan oleh setiap tool.

`ToolOutputSchemas`

Union dari semua tipe output tool.

type ToolOutputSchemas =
  | AgentOutput
  | AskUserQuestionOutput
  | BashOutput
  | ConfigOutput
  | EnterWorktreeOutput
  | ExitPlanModeOutput
  | FileEditOutput
  | FileReadOutput
  | FileWriteOutput
  | GlobOutput
  | GrepOutput
  | ListMcpResourcesOutput
  | MonitorOutput
  | NotebookEditOutput
  | ReadMcpResourceOutput
  | TaskStopOutput
  | TodoWriteOutput
  | WebFetchOutput
  | WebSearchOutput;

Agent

Nama tool: Agent (sebelumnya Task, yang masih diterima sebagai alias)

type AgentOutput =
  | {
      status: "completed";
      agentId: string;
      content: Array<{ type: "text"; text: 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;
      prompt: string;
      outputFile: string;
      canReadOutputFile?: boolean;
    }
  | {
      status: "sub_agent_entered";
      description: string;
      message: string;
    };

Mengembalikan hasil dari subagen. Didiskriminasikan pada field status: "completed" untuk tugas yang selesai, "async_launched" untuk tugas latar belakang, dan "sub_agent_entered" untuk subagen interaktif.

AskUserQuestion

Nama tool: AskUserQuestion

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

Mengembalikan pertanyaan yang diajukan dan jawaban pengguna.

Bash

Nama tool: 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;
};

Mengembalikan output perintah dengan stdout/stderr terpisah. Perintah latar belakang menyertakan backgroundTaskId.

Monitor

Nama tool: Monitor

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

Mengembalikan ID tugas latar belakang untuk monitor yang sedang berjalan. Gunakan ID ini dengan TaskStop untuk membatalkan watch lebih awal.

Edit

Nama tool: 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;
  };
};

Mengembalikan diff terstruktur dari operasi edit.

Read

Nama tool: 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;
      };
    };

Mengembalikan konten file dalam format yang sesuai dengan tipe file. Didiskriminasikan pada field type.

Write

Nama tool: 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;
  };
};

Mengembalikan hasil write dengan informasi diff terstruktur.

Glob

Nama tool: Glob

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

Mengembalikan jalur file yang cocok dengan pola glob, diurutkan berdasarkan waktu modifikasi.

Grep

Nama tool: Grep

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

Mengembalikan hasil pencarian. Bentuknya bervariasi menurut mode: daftar file, konten dengan kecocokan, atau hitungan kecocokan.

TaskStop

Nama tool: TaskStop

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

Mengembalikan konfirmasi setelah menghentikan tugas latar belakang.

NotebookEdit

Nama tool: 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;
};

Mengembalikan hasil edit notebook dengan konten file asli dan diperbarui.

WebFetch

Nama tool: WebFetch

type WebFetchOutput = {
  bytes: number;
  code: number;
  codeText: string;
  result: string;
  durationMs: number;
  url: string;
};

Mengembalikan konten yang diambil dengan status HTTP dan metadata.

WebSearch

Nama tool: WebSearch

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

Mengembalikan hasil pencarian dari web.

TodoWrite

Nama tool: 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;
  }>;
};

Mengembalikan daftar tugas sebelumnya dan diperbarui.

ExitPlanMode

Nama tool: ExitPlanMode

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

Mengembalikan status rencana setelah keluar dari mode perencanaan.

ListMcpResources

Nama tool: ListMcpResources

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

Mengembalikan array sumber daya MCP yang tersedia.

ReadMcpResource

Nama tool: ReadMcpResource

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

Mengembalikan konten sumber daya MCP yang diminta.

Config

Nama tool: Config

type ConfigOutput = {
  success: boolean;
  operation?: "get" | "set";
  setting?: string;
  value?: unknown;
  previousValue?: unknown;
  newValue?: unknown;
  error?: string;
};

Mengembalikan hasil operasi get atau set konfigurasi.

EnterWorktree

Nama tool: EnterWorktree

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

Mengembalikan informasi tentang worktree git.

Tipe Izin

`PermissionUpdate`

Operasi untuk memperbarui izin.

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" // Pengaturan pengguna global
  | "projectSettings" // Pengaturan proyek per-direktori
  | "localSettings" // Pengaturan lokal gitignored
  | "session" // Hanya sesi saat ini
  | "cliArg"; // Argumen CLI

`PermissionRuleValue`

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

Tipe Lainnya

`ApiKeySource`

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

`SdkBeta`

Fitur beta yang tersedia yang dapat diaktifkan melalui opsi betas. Lihat Beta headers untuk informasi lebih lanjut.

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

Beta context-1m-2025-08-07 sudah pensiun sejak 30 April 2026. Melewatkan nilai ini dengan Claude Sonnet 4.5 atau Sonnet 4 tidak berpengaruh, dan permintaan yang melebihi jendela konteks standar 200k-token mengembalikan error. Untuk menggunakan jendela konteks 1M-token, migrasikan ke Claude Sonnet 4.6, Claude Opus 4.6, atau Claude Opus 4.7, yang mencakup konteks 1M dengan harga standar tanpa header beta yang diperlukan.

`SlashCommand`

Informasi tentang perintah slash yang tersedia.

type SlashCommand = {
  name: string;
  description: string;
  argumentHint: string;
};

`ModelInfo`

Informasi tentang model yang tersedia.

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

`AgentInfo`

Informasi tentang subagen yang tersedia yang dapat dipanggil melalui tool Agent.

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

Field	Tipe	Deskripsi
`name`	`string`	Pengenal tipe agen (misalnya, `"Explore"`, `"general-purpose"`)
`description`	`string`	Deskripsi tentang kapan menggunakan agen ini
`model`	`string \| undefined`	Alias model yang digunakan agen ini. Jika dihilangkan, mewarisi model parent

`McpServerStatus`

Status server MCP yang terhubung.

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`

Konfigurasi server MCP seperti yang dilaporkan oleh mcpServerStatus(). Ini adalah union dari semua tipe transport server MCP.

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

Lihat McpServerConfig untuk detail tentang setiap tipe transport.

`AccountInfo`

Informasi akun untuk pengguna yang diautentikasi.

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

`ModelUsage`

Statistik penggunaan per-model yang dikembalikan dalam pesan hasil. Nilai costUSD adalah estimasi sisi klien. Lihat Lacak biaya dan penggunaan untuk peringatan penagihan.

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`

Versi Usage dengan semua field nullable dibuat non-nullable.

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

`Usage`

Statistik penggunaan token (dari @anthropic-ai/sdk).

type Usage = {
  input_tokens: number | null;
  output_tokens: number | null;
  cache_creation_input_tokens?: number | null;
  cache_read_input_tokens?: number | null;
};

`CallToolResult`

Tipe hasil tool MCP (dari @modelcontextprotocol/sdk/types.js).

type CallToolResult = {
  content: Array<{
    type: "text" | "image" | "resource";
    // Field tambahan bervariasi menurut tipe
  }>;
  isError?: boolean;
};

`ThinkingConfig`

Mengontrol perilaku pemikiran/penalaran Claude. Mengambil preseden atas maxThinkingTokens yang sudah usang.

type ThinkingConfig =
  | { type: "adaptive" } // Model menentukan kapan dan berapa banyak untuk bernalar (Opus 4.6+)
  | { type: "enabled"; budgetTokens?: number } // Anggaran token pemikiran tetap
  | { type: "disabled" }; // Tidak ada pemikiran yang diperluas

`SpawnedProcess`

Antarmuka untuk spawn proses kustom (digunakan dengan opsi spawnClaudeCodeProcess). ChildProcess sudah memenuhi antarmuka ini.

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`

Opsi yang diteruskan ke fungsi spawn kustom.

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

`McpSetServersResult`

Hasil operasi setMcpServers().

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

`RewindFilesResult`

Hasil operasi rewindFiles().

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

`SDKStatusMessage`

Pesan pembaruan status (misalnya, pemadatan).

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

`SDKTaskNotificationMessage`

Notifikasi ketika tugas latar belakang selesai, gagal, atau dihentikan. Tugas latar belakang mencakup perintah Bash run_in_background, watch Monitor, dan subagen latar belakang.

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`

Ringkasan penggunaan tool dalam percakapan.

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

`SDKHookStartedMessage`

Dipancarkan ketika hook mulai mengeksekusi.

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

`SDKHookProgressMessage`

Dipancarkan saat hook sedang berjalan, dengan output 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`

Dipancarkan ketika hook selesai mengeksekusi.

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`

Dipancarkan secara berkala saat tool sedang mengeksekusi untuk menunjukkan kemajuan.

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`

Dipancarkan selama alur autentikasi.

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

`SDKTaskStartedMessage`

Dipancarkan ketika tugas latar belakang dimulai. Field task_type adalah "local_bash" untuk perintah Bash latar belakang dan watch Monitor, "local_agent" untuk subagen, atau "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`

Dipancarkan secara berkala saat tugas latar belakang sedang berjalan.

type SDKTaskProgressMessage = {
  type: "system";
  subtype: "task_progress";
  task_id: string;
  tool_use_id?: string;
  description: string;
  usage: {
    total_tokens: number;
    tool_uses: number;
    duration_ms: number;
  };
  last_tool_name?: string;
  uuid: UUID;
  session_id: string;
};

`SDKFilesPersistedEvent`

Dipancarkan ketika checkpoint file dipersistenkan ke disk.

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`

Dipancarkan ketika sesi mengalami batas laju.

type SDKRateLimitEvent = {
  type: "rate_limit_event";
  rate_limit_info: {
    status: "allowed" | "allowed_warning" | "rejected";
    resetsAt?: number;
    utilization?: number;
  };
  uuid: UUID;
  session_id: string;
};

`SDKLocalCommandOutputMessage`

Output dari perintah slash lokal (misalnya, /voice atau /cost). Ditampilkan sebagai teks gaya asisten dalam transkrip.

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

`SDKPromptSuggestionMessage`

Dipancarkan setelah setiap putaran ketika promptSuggestions diaktifkan. Berisi prompt pengguna berikutnya yang diprediksi.

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

`AbortError`

Kelas error kustom untuk operasi abort.

class AbortError extends Error {}

Konfigurasi Sandbox

`SandboxSettings`

Konfigurasi untuk perilaku sandbox. Gunakan ini untuk mengaktifkan sandboxing perintah dan mengonfigurasi pembatasan jaringan secara terprogram.

type SandboxSettings = {
  enabled?: boolean;
  autoAllowBashIfSandboxed?: boolean;
  excludedCommands?: string[];
  allowUnsandboxedCommands?: boolean;
  network?: SandboxNetworkConfig;
  filesystem?: SandboxFilesystemConfig;
  ignoreViolations?: Record<string, string[]>;
  enableWeakerNestedSandbox?: boolean;
  ripgrep?: { command: string; args?: string[] };
};

Properti	Tipe	Default	Deskripsi
`enabled`	`boolean`	`false`	Aktifkan mode sandbox untuk eksekusi perintah
`autoAllowBashIfSandboxed`	`boolean`	`true`	Auto-approve perintah bash ketika sandbox diaktifkan
`excludedCommands`	`string[]`	`[]`	Perintah yang selalu bypass pembatasan sandbox (misalnya, `['docker']`). Ini berjalan unsandboxed secara otomatis tanpa keterlibatan model
`allowUnsandboxedCommands`	`boolean`	`true`	Izinkan model untuk meminta menjalankan perintah di luar sandbox. Ketika `true`, model dapat mengatur `dangerouslyDisableSandbox` dalam input tool, yang jatuh kembali ke sistem izin
`network`	`SandboxNetworkConfig`	`undefined`	Konfigurasi sandbox spesifik jaringan
`filesystem`	`SandboxFilesystemConfig`	`undefined`	Konfigurasi sandbox spesifik filesystem untuk pembatasan baca/tulis
`ignoreViolations`	`Record<string, string[]>`	`undefined`	Peta kategori pelanggaran ke pola untuk diabaikan (misalnya, `{ file: ['/tmp/*'], network: ['localhost'] }`)
`enableWeakerNestedSandbox`	`boolean`	`false`	Aktifkan sandbox bersarang yang lebih lemah untuk kompatibilitas
`ripgrep`	`{ command: string; args?: string[] }`	`undefined`	Konfigurasi biner ripgrep kustom untuk lingkungan sandbox

Contoh penggunaan

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

Keamanan Unix socket: Opsi allowUnixSockets dapat memberikan akses ke layanan sistem yang kuat. Misalnya, mengizinkan /var/run/docker.sock secara efektif memberikan akses sistem host penuh melalui API Docker, melewati isolasi sandbox. Hanya izinkan Unix socket yang benar-benar diperlukan dan pahami implikasi keamanan dari masing-masing.

`SandboxNetworkConfig`

Konfigurasi spesifik jaringan untuk mode sandbox.

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

Properti	Tipe	Default	Deskripsi
`allowedDomains`	`string[]`	`[]`	Nama domain yang dapat diakses proses sandboxed
`deniedDomains`	`string[]`	`[]`	Nama domain yang tidak dapat diakses proses sandboxed. Mengambil prioritas atas `allowedDomains`
`allowManagedDomainsOnly`	`boolean`	`false`	Batasi akses jaringan hanya ke domain dalam `allowedDomains`
`allowLocalBinding`	`boolean`	`false`	Izinkan proses untuk mengikat ke port lokal (misalnya, untuk dev server)
`allowUnixSockets`	`string[]`	`[]`	Jalur Unix socket yang dapat diakses proses (misalnya, Docker socket)
`allowAllUnixSockets`	`boolean`	`false`	Izinkan akses ke semua Unix socket
`httpProxyPort`	`number`	`undefined`	Port proxy HTTP untuk permintaan jaringan
`socksProxyPort`	`number`	`undefined`	Port proxy SOCKS untuk permintaan jaringan

`SandboxFilesystemConfig`

Konfigurasi spesifik filesystem untuk mode sandbox.

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

Properti	Tipe	Default	Deskripsi
`allowWrite`	`string[]`	`[]`	Pola jalur file untuk mengizinkan akses tulis ke
`denyWrite`	`string[]`	`[]`	Pola jalur file untuk menolak akses tulis ke
`denyRead`	`string[]`	`[]`	Pola jalur file untuk menolak akses baca ke

Fallback Izin untuk Perintah Unsandboxed

Ketika allowUnsandboxedCommands diaktifkan, model dapat meminta untuk menjalankan perintah di luar sandbox dengan mengatur dangerouslyDisableSandbox: true dalam input tool. Permintaan ini jatuh kembali ke sistem izin yang ada, berarti handler canUseTool Anda dipanggil, memungkinkan Anda untuk mengimplementasikan logika otorisasi kustom.

excludedCommands vs allowUnsandboxedCommands:

excludedCommands: Daftar statis perintah yang selalu bypass sandbox secara otomatis (misalnya, ['docker']). Model tidak memiliki kontrol atas ini.
allowUnsandboxedCommands: Biarkan model memutuskan pada runtime apakah akan meminta eksekusi unsandboxed dengan mengatur dangerouslyDisableSandbox: true dalam input tool.

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 dapat meminta eksekusi unsandboxed
    },
    permissionMode: "default",
    canUseTool: async (tool, input) => {
      // Periksa apakah model meminta untuk bypass sandbox
      if (tool === "Bash" && input.dangerouslyDisableSandbox) {
        // Model meminta untuk menjalankan perintah ini di luar 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);
}

Pola ini memungkinkan Anda untuk:

Audit permintaan model: Catat ketika model meminta eksekusi unsandboxed
Implementasikan allowlist: Hanya izinkan perintah tertentu untuk berjalan unsandboxed
Tambahkan alur persetujuan: Memerlukan otorisasi eksplisit untuk operasi istimewa

Perintah yang berjalan dengan dangerouslyDisableSandbox: true memiliki akses sistem penuh. Pastikan handler canUseTool Anda memvalidasi permintaan ini dengan hati-hati.Jika permissionMode diatur ke bypassPermissions dan allowUnsandboxedCommands diaktifkan, model dapat secara otonom mengeksekusi perintah di luar sandbox tanpa prompt persetujuan apa pun. Kombinasi ini secara efektif memungkinkan model untuk melarikan diri dari isolasi sandbox secara diam-diam.

Lihat juga

Gambaran umum SDK - Konsep SDK umum
Referensi SDK Python - Dokumentasi SDK Python
Referensi CLI - Antarmuka baris perintah
Alur kerja umum - Panduan langkah demi langkah

Agent SDK

Konsep Inti

Input dan output

Perluas dengan tools

Sesuaikan perilaku

Kontrol dan observabilitas

Penerapan

Referensi SDK

​Instalasi

​Fungsi

​query()

​Parameter

​Pengembalian

​startup()

​Parameter

​Pengembalian

​Contoh

​tool()

​Parameter

​ToolAnnotations

​createSdkMcpServer()

​Parameter

​listSessions()

​Parameter

​Tipe pengembalian: SDKSessionInfo

​Contoh

​getSessionMessages()

​Parameter

​Tipe pengembalian: SessionMessage

​Contoh

​getSessionInfo()

​Parameter

​renameSession()

​Parameter

​tagSession()

​Parameter

​Tipe

​Options

​Objek Query

​Metode

​WarmQuery

​Metode

​SDKControlInitializeResponse

​AgentDefinition

​AgentMcpServerSpec

​SettingSource

​Perilaku default

​Mengapa menggunakan settingSources

​Preseden pengaturan

​PermissionMode

​CanUseTool

​PermissionResult

​ToolConfig

​McpServerConfig

​McpStdioServerConfig

​McpSSEServerConfig

​McpHttpServerConfig

​McpSdkServerConfigWithInstance

​McpClaudeAIProxyServerConfig

​SdkPluginConfig

​Tipe Pesan

​SDKMessage

​SDKAssistantMessage

​SDKUserMessage

​SDKUserMessageReplay

​SDKResultMessage

​SDKSystemMessage

​SDKPartialAssistantMessage

​SDKCompactBoundaryMessage

​SDKPluginInstallMessage

​SDKPermissionDenial

​Tipe Hook

​HookEvent

​HookCallback

​HookCallbackMatcher

​HookInput

​BaseHookInput

​PreToolUseHookInput

​PostToolUseHookInput

​PostToolUseFailureHookInput

Instalasi

Fungsi

`query()`

Parameter

Pengembalian

`startup()`

Parameter

Pengembalian

Contoh

`tool()`

Parameter

`ToolAnnotations`

`createSdkMcpServer()`

Parameter

`listSessions()`

Parameter

Tipe pengembalian: `SDKSessionInfo`

Contoh

`getSessionMessages()`

Parameter

Tipe pengembalian: `SessionMessage`

Contoh

`getSessionInfo()`

Parameter

`renameSession()`

Parameter

`tagSession()`

Parameter

Tipe

`Options`

Objek `Query`

Metode

`WarmQuery`

Metode

`SDKControlInitializeResponse`

`AgentDefinition`

`AgentMcpServerSpec`

`SettingSource`

Perilaku default

Mengapa menggunakan settingSources

Preseden pengaturan

`PermissionMode`

`CanUseTool`

`PermissionResult`

`ToolConfig`

`McpServerConfig`

`McpStdioServerConfig`

`McpSSEServerConfig`

`McpHttpServerConfig`

`McpSdkServerConfigWithInstance`

`McpClaudeAIProxyServerConfig`

`SdkPluginConfig`

Tipe Pesan

`SDKMessage`

`SDKAssistantMessage`

`SDKUserMessage`

`SDKUserMessageReplay`

`SDKResultMessage`

`SDKSystemMessage`

`SDKPartialAssistantMessage`

`SDKCompactBoundaryMessage`

`SDKPluginInstallMessage`

`SDKPermissionDenial`

Tipe Hook

`HookEvent`

`HookCallback`

`HookCallbackMatcher`

`HookInput`

`BaseHookInput`

`PreToolUseHookInput`

`PostToolUseHookInput`

`PostToolUseFailureHookInput`

`NotificationHookInput`

`UserPromptSubmitHookInput`

`SessionStartHookInput`

`SessionEndHookInput`

`StopHookInput`

`SubagentStartHookInput`

`SubagentStopHookInput`

`PreCompactHookInput`