Riferimento Agent SDK - TypeScript

Prova la nuova interfaccia V2 (anteprima): Un’interfaccia semplificata con i pattern send() e stream() è ora disponibile, rendendo le conversazioni multi-turno più facili. Scopri di più sull’anteprima TypeScript V2

Installazione

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

L’SDK raggruppa un binario nativo Claude Code per la tua piattaforma come dipendenza opzionale come @anthropic-ai/claude-agent-sdk-darwin-arm64. Non è necessario installare Claude Code separatamente. Se il tuo gestore di pacchetti salta le dipendenze opzionali, l’SDK genera Native CLI binary for <platform> not found; imposta pathToClaudeCodeExecutable su un binario claude installato separatamente.

Funzioni

`query()`

La funzione principale per interagire con Claude Code. Crea un generatore asincrono che trasmette i messaggi man mano che arrivano.

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

Parametri

Parametro	Tipo	Descrizione
`prompt`	`string \| AsyncIterable<SDKUserMessage>`	Il prompt di input come stringa o iterabile asincrono per la modalità streaming
`options`	`Options`	Oggetto di configurazione opzionale (vedi il tipo Options di seguito)

Restituisce

Restituisce un oggetto Query che estende AsyncGenerator<SDKMessage, void> con metodi aggiuntivi.

`startup()`

Pre-riscalda il subprocess CLI generandolo e completando l’handshake di inizializzazione prima che un prompt sia disponibile. L’handle WarmQuery restituito accetta un prompt in seguito e lo scrive in un processo già pronto, quindi la prima chiamata query() si risolve senza pagare il costo di generazione e inizializzazione del subprocess inline.

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

Parametri

Parametro	Tipo	Descrizione
`options`	`Options`	Oggetto di configurazione opzionale. Uguale al parametro `options` di `query()`
`initializeTimeoutMs`	`number`	Tempo massimo in millisecondi per attendere l’inizializzazione del subprocess. Predefinito a `60000`. Se l’inizializzazione non si completa in tempo, la promessa viene rifiutata con un errore di timeout

Restituisce

Restituisce una Promise<WarmQuery> che si risolve una volta che il subprocess è stato generato e ha completato il suo handshake di inizializzazione.

Esempio

Chiama startup() presto, ad esempio all’avvio dell’applicazione, quindi chiama .query() sull’handle restituito una volta che un prompt è pronto. Questo sposta la generazione del subprocess e l’inizializzazione fuori dal percorso critico.

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

// Paga il costo di avvio in anticipo
const warm = await startup({ options: { maxTurns: 3 } });

// Più tardi, quando un prompt è pronto, questo è immediato
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

`tool()`

Crea una definizione di tool MCP type-safe per l’uso con i server MCP dell’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>;

Parametri

Parametro	Tipo	Descrizione
`name`	`string`	Il nome del tool
`description`	`string`	Una descrizione di cosa fa il tool
`inputSchema`	`Schema extends AnyZodRawShape`	Schema Zod che definisce i parametri di input del tool (supporta sia Zod 3 che Zod 4)
`handler`	`(args, extra) => Promise<CallToolResult>`	Funzione asincrona che esegue la logica del tool
`extras`	`{ annotations?:` `ToolAnnotations` `}`	Annotazioni MCP tool opzionali che forniscono suggerimenti comportamentali ai client

`ToolAnnotations`

Re-esportato da @modelcontextprotocol/sdk/types.js. Tutti i campi sono suggerimenti opzionali; i client non dovrebbero fare affidamento su di essi per decisioni di sicurezza.

Campo	Tipo	Predefinito	Descrizione
`title`	`string`	`undefined`	Titolo leggibile per il tool
`readOnlyHint`	`boolean`	`false`	Se `true`, il tool non modifica il suo ambiente
`destructiveHint`	`boolean`	`true`	Se `true`, il tool può eseguire aggiornamenti distruttivi (significativo solo quando `readOnlyHint` è `false`)
`idempotentHint`	`boolean`	`false`	Se `true`, le chiamate ripetute con gli stessi argomenti non hanno effetto aggiuntivo (significativo solo quando `readOnlyHint` è `false`)
`openWorldHint`	`boolean`	`true`	Se `true`, il tool interagisce con entità esterne (ad esempio, ricerca web). Se `false`, il dominio del tool è chiuso (ad esempio, un tool di memoria)

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

Crea un’istanza di server MCP che viene eseguita nello stesso processo della tua applicazione.

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

Parametri

Parametro	Tipo	Descrizione
`options.name`	`string`	Il nome del server MCP
`options.version`	`string`	Stringa di versione opzionale
`options.tools`	`Array<SdkMcpToolDefinition>`	Array di definizioni di tool create con `tool()`

`listSessions()`

Scopre ed elenca le sessioni passate con metadati leggeri. Filtra per directory di progetto o elenca le sessioni in tutti i progetti.

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

Parametri

Parametro	Tipo	Predefinito	Descrizione
`options.dir`	`string`	`undefined`	Directory per cui elencare le sessioni. Se omesso, restituisce le sessioni in tutti i progetti
`options.limit`	`number`	`undefined`	Numero massimo di sessioni da restituire
`options.includeWorktrees`	`boolean`	`true`	Quando `dir` si trova all’interno di un repository git, includi le sessioni da tutti i percorsi worktree

Tipo di ritorno: `SDKSessionInfo`

Proprietà	Tipo	Descrizione
`sessionId`	`string`	Identificatore di sessione univoco (UUID)
`summary`	`string`	Titolo di visualizzazione: titolo personalizzato, riepilogo generato automaticamente o primo prompt
`lastModified`	`number`	Ora dell’ultima modifica in millisecondi dall’epoca
`fileSize`	`number \| undefined`	Dimensione del file di sessione in byte. Popolato solo per l’archiviazione JSONL locale
`customTitle`	`string \| undefined`	Titolo della sessione impostato dall’utente (tramite `/rename`)
`firstPrompt`	`string \| undefined`	Primo prompt utente significativo nella sessione
`gitBranch`	`string \| undefined`	Ramo Git alla fine della sessione
`cwd`	`string \| undefined`	Directory di lavoro per la sessione
`tag`	`string \| undefined`	Tag della sessione impostato dall’utente (vedi `tagSession()`)
`createdAt`	`number \| undefined`	Ora di creazione in millisecondi dall’epoca, dal timestamp della prima voce

Esempio

Stampa le 10 sessioni più recenti per un progetto. I risultati sono ordinati per lastModified decrescente, quindi il primo elemento è il più recente. Ometti dir per cercare in tutti i progetti.

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

Legge i messaggi dell’utente e dell’assistente da una trascrizione di sessione passata.

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

Parametri

Parametro	Tipo	Predefinito	Descrizione
`sessionId`	`string`	obbligatorio	UUID della sessione da leggere (vedi `listSessions()`)
`options.dir`	`string`	`undefined`	Directory del progetto in cui trovare la sessione. Se omesso, cerca in tutti i progetti
`options.limit`	`number`	`undefined`	Numero massimo di messaggi da restituire
`options.offset`	`number`	`undefined`	Numero di messaggi da saltare dall’inizio

Tipo di ritorno: `SessionMessage`

Proprietà	Tipo	Descrizione
`type`	`"user" \| "assistant"`	Ruolo del messaggio
`uuid`	`string`	Identificatore di messaggio univoco
`session_id`	`string`	Sessione a cui appartiene questo messaggio
`message`	`unknown`	Payload del messaggio grezzo dalla trascrizione
`parent_tool_use_id`	`null`	Riservato

Esempio

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

Legge i metadati per una singola sessione per ID senza scansionare la directory del progetto completa.

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

Parametri

Parametro	Tipo	Predefinito	Descrizione
`sessionId`	`string`	obbligatorio	UUID della sessione da cercare
`options.dir`	`string`	`undefined`	Percorso della directory del progetto. Se omesso, cerca in tutte le directory del progetto

Restituisce SDKSessionInfo, o undefined se la sessione non viene trovata.

`renameSession()`

Rinomina una sessione aggiungendo una voce di titolo personalizzato. Le chiamate ripetute sono sicure; il titolo più recente vince.

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

Parametri

Parametro	Tipo	Predefinito	Descrizione
`sessionId`	`string`	obbligatorio	UUID della sessione da rinominare
`title`	`string`	obbligatorio	Nuovo titolo. Deve essere non vuoto dopo il trimming dello spazio bianco
`options.dir`	`string`	`undefined`	Percorso della directory del progetto. Se omesso, cerca in tutte le directory del progetto

`tagSession()`

Etichetta una sessione. Passa null per cancellare l’etichetta. Le chiamate ripetute sono sicure; l’etichetta più recente vince.

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

Parametri

Parametro	Tipo	Predefinito	Descrizione
`sessionId`	`string`	obbligatorio	UUID della sessione da etichettare
`tag`	`string \| null`	obbligatorio	Stringa di etichetta, o `null` per cancellare
`options.dir`	`string`	`undefined`	Percorso della directory del progetto. Se omesso, cerca in tutte le directory del progetto

Tipi

`Options`

Oggetto di configurazione per la funzione query().

Proprietà	Tipo	Predefinito	Descrizione
`abortController`	`AbortController`	`new AbortController()`	Controller per annullare le operazioni
`additionalDirectories`	`string[]`	`[]`	Directory aggiuntive a cui Claude può accedere
`agent`	`string`	`undefined`	Nome dell’agente per il thread principale. L’agente deve essere definito nell’opzione `agents` o nelle impostazioni
`agents`	`Record<string, [`AgentDefinition`](#agent-definition)>`	`undefined`	Definisci programmaticamente i subagenti
`allowDangerouslySkipPermissions`	`boolean`	`false`	Abilita il bypass dei permessi. Obbligatorio quando si usa `permissionMode: 'bypassPermissions'`
`allowedTools`	`string[]`	`[]`	Tool da approvare automaticamente senza richiedere. Questo non limita Claude a solo questi tool; i tool non elencati ricadono in `permissionMode` e `canUseTool`. Usa `disallowedTools` per bloccare i tool. Vedi Permessi
`betas`	`SdkBeta[]`	`[]`	Abilita le funzioni beta
`canUseTool`	`CanUseTool`	`undefined`	Funzione di permesso personalizzata per l’uso dei tool
`continue`	`boolean`	`false`	Continua la conversazione più recente
`cwd`	`string`	`process.cwd()`	Directory di lavoro corrente
`debug`	`boolean`	`false`	Abilita la modalità debug per il processo Claude Code
`debugFile`	`string`	`undefined`	Scrivi i log di debug in un percorso di file specifico. Abilita implicitamente la modalità debug
`disallowedTools`	`string[]`	`[]`	Tool da sempre negare. Le regole di negazione vengono controllate per prime e sovrascrivono `allowedTools` e `permissionMode` (incluso `bypassPermissions`)
`effort`	`'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'`	`'high'`	Controlla quanto sforzo Claude mette nella sua risposta. Funziona con il pensiero adattivo per guidare la profondità del pensiero
`enableFileCheckpointing`	`boolean`	`false`	Abilita il tracciamento dei cambiamenti di file per il rewind. Vedi File checkpointing
`env`	`Record<string, string \| undefined>`	`process.env`	Variabili di ambiente. Imposta `CLAUDE_AGENT_SDK_CLIENT_APP` per identificare la tua app nell’intestazione User-Agent
`executable`	`'bun' \| 'deno' \| 'node'`	Auto-rilevato	Runtime JavaScript da usare
`executableArgs`	`string[]`	`[]`	Argomenti da passare all’eseguibile
`extraArgs`	`Record<string, string \| null>`	`{}`	Argomenti aggiuntivi
`fallbackModel`	`string`	`undefined`	Modello da usare se il primario fallisce
`forkSession`	`boolean`	`false`	Quando si riprende con `resume`, esegui il fork a un nuovo ID di sessione invece di continuare la sessione originale
`hooks`	`Partial<Record<HookEvent,` `HookCallbackMatcher[]>>`	`{}`	Callback hook per gli eventi
`includePartialMessages`	`boolean`	`false`	Includi gli eventi di messaggi parziali
`maxBudgetUsd`	`number`	`undefined`	Interrompi la query quando la stima del costo lato client raggiunge questo valore in USD. Confrontato con la stessa stima di `total_cost_usd`; vedi Traccia costo e utilizzo per le avvertenze di accuratezza
`maxThinkingTokens`	`number`	`undefined`	Deprecato: Usa `thinking` invece. Token massimi per il processo di pensiero
`maxTurns`	`number`	`undefined`	Turni agentici massimi (round trip di uso dei tool)
`mcpServers`	`Record<string, [`McpServerConfig`](#mcp-server-config)>`	`{}`	Configurazioni del server MCP
`model`	`string`	Predefinito da CLI	Modello Claude da usare
`outputFormat`	`{ type: 'json_schema', schema: JSONSchema }`	`undefined`	Definisci il formato di output per i risultati dell’agente. Vedi Output strutturati per i dettagli
`pathToClaudeCodeExecutable`	`string`	Auto-risolto dal binario nativo raggruppato	Percorso all’eseguibile Claude Code. Necessario solo se le dipendenze opzionali sono state saltate durante l’installazione o la tua piattaforma non è nel set supportato
`permissionMode`	`PermissionMode`	`'default'`	Modalità di permesso per la sessione
`permissionPromptToolName`	`string`	`undefined`	Nome del tool MCP per i prompt di permesso
`persistSession`	`boolean`	`true`	Quando `false`, disabilita la persistenza della sessione su disco. Le sessioni non possono essere riprese in seguito
`plugins`	`SdkPluginConfig[]`	`[]`	Carica plugin personalizzati da percorsi locali. Vedi Plugins per i dettagli
`promptSuggestions`	`boolean`	`false`	Abilita i suggerimenti di prompt. Emette un messaggio `prompt_suggestion` dopo ogni turno con un prompt utente successivo previsto
`resume`	`string`	`undefined`	ID della sessione da riprendere
`resumeSessionAt`	`string`	`undefined`	Riprendi la sessione a un UUID di messaggio specifico
`sandbox`	`SandboxSettings`	`undefined`	Configura il comportamento della sandbox a livello di programmazione. Vedi Impostazioni sandbox per i dettagli
`sessionId`	`string`	Auto-generato	Usa un UUID specifico per la sessione invece di generarne uno automaticamente
`settingSources`	`SettingSource[]`	Impostazioni predefinite CLI (tutte le fonti)	Controlla quali impostazioni del filesystem caricare. Passa `[]` per disabilitare le impostazioni utente, progetto e locali. Le impostazioni della politica gestita vengono caricate indipendentemente. Vedi Usa le funzioni Claude Code
`spawnClaudeCodeProcess`	`(options: SpawnOptions) => SpawnedProcess`	`undefined`	Funzione personalizzata per generare il processo Claude Code. Usa per eseguire Claude Code in VM, container o ambienti remoti
`stderr`	`(data: string) => void`	`undefined`	Callback per l’output stderr
`strictMcpConfig`	`boolean`	`false`	Applica la convalida MCP rigorosa
`systemPrompt`	`string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }`	`undefined` (prompt minimo)	Configurazione del prompt di sistema. Passa una stringa per un prompt personalizzato, o `{ type: 'preset', preset: 'claude_code' }` per usare il prompt di sistema di Claude Code. Quando si usa la forma dell’oggetto preset, aggiungi `append` per estenderlo con istruzioni aggiuntive, e imposta `excludeDynamicSections: true` per spostare il contesto per sessione nel primo messaggio utente per un migliore riutilizzo della cache dei prompt tra le macchine
`thinking`	`ThinkingConfig`	`{ type: 'adaptive' }` per i modelli supportati	Controlla il comportamento di pensiero/ragionamento di Claude. Vedi `ThinkingConfig` per le opzioni
`toolConfig`	`ToolConfig`	`undefined`	Configurazione per il comportamento dei tool incorporati. Vedi `ToolConfig` per i dettagli
`tools`	`string[] \| { type: 'preset'; preset: 'claude_code' }`	`undefined`	Configurazione dei tool. Passa un array di nomi di tool o usa il preset per ottenere i tool predefiniti di Claude Code

Oggetto `Query`

Interfaccia restituita dalla funzione 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;
}

Metodi

Metodo	Descrizione
`interrupt()`	Interrompe la query (disponibile solo in modalità input streaming)
`rewindFiles(userMessageId, options?)`	Ripristina i file al loro stato al messaggio utente specificato. Passa `{ dryRun: true }` per visualizzare in anteprima i cambiamenti. Richiede `enableFileCheckpointing: true`. Vedi File checkpointing
`setPermissionMode()`	Cambia la modalità di permesso (disponibile solo in modalità input streaming)
`setModel()`	Cambia il modello (disponibile solo in modalità input streaming)
`setMaxThinkingTokens()`	Deprecato: Usa l’opzione `thinking` invece. Cambia i token di pensiero massimi
`initializationResult()`	Restituisce il risultato di inizializzazione completo inclusi i comandi supportati, i modelli, le informazioni dell’account e la configurazione dello stile di output
`supportedCommands()`	Restituisce i comandi slash disponibili
`supportedModels()`	Restituisce i modelli disponibili con le informazioni di visualizzazione
`supportedAgents()`	Restituisce i subagenti disponibili come `AgentInfo[]`
`mcpServerStatus()`	Restituisce lo stato dei server MCP connessi
`accountInfo()`	Restituisce le informazioni dell’account
`reconnectMcpServer(serverName)`	Ricollega un server MCP per nome
`toggleMcpServer(serverName, enabled)`	Abilita o disabilita un server MCP per nome
`setMcpServers(servers)`	Sostituisci dinamicamente l’insieme dei server MCP per questa sessione. Restituisce informazioni su quali server sono stati aggiunti, rimossi e eventuali errori
`streamInput(stream)`	Trasmetti i messaggi di input alla query per le conversazioni multi-turno
`stopTask(taskId)`	Interrompi un’attività di background in esecuzione per ID
`close()`	Chiudi la query e termina il processo sottostante. Termina forzatamente la query e pulisce tutte le risorse

`WarmQuery`

Handle restituito da startup(). Il subprocess è già generato e inizializzato, quindi chiamare query() su questo handle scrive il prompt direttamente in un processo pronto senza latenza di avvio.

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

Metodi

Metodo	Descrizione
`query(prompt)`	Invia un prompt al subprocess pre-riscaldato e restituisci una `Query`. Può essere chiamato solo una volta per `WarmQuery`
`close()`	Chiudi il subprocess senza inviare un prompt. Usa questo per scartare una query calda che non è più necessaria

WarmQuery implementa AsyncDisposable, quindi può essere usato con await using per la pulizia automatica.

`SDKControlInitializeResponse`

Tipo di ritorno di initializationResult(). Contiene i dati di inizializzazione della sessione.

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

`AgentDefinition`

Configurazione per un subagente definito programmaticamente.

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

Campo	Obbligatorio	Descrizione
`description`	Sì	Descrizione in linguaggio naturale di quando usare questo agente
`tools`	No	Array di nomi di tool consentiti. Se omesso, eredita tutti i tool dal genitore
`disallowedTools`	No	Array di nomi di tool da esplicitamente disabilitare per questo agente
`prompt`	Sì	Il prompt di sistema dell’agente
`model`	No	Override del modello per questo agente. Se omesso o `'inherit'`, usa il modello principale
`mcpServers`	No	Specifiche del server MCP per questo agente
`skills`	No	Array di nomi di skill da precaricare nel contesto dell’agente
`maxTurns`	No	Numero massimo di turni agentici (round trip API) prima di fermarsi
`criticalSystemReminder_EXPERIMENTAL`	No	Sperimentale: Promemoria critico aggiunto al prompt di sistema

`AgentMcpServerSpec`

Specifica i server MCP disponibili per un subagente. Può essere un nome di server (stringa che fa riferimento a un server dalla configurazione mcpServers del genitore) o una configurazione di server inline che mappa i nomi dei server alle configurazioni.

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

Dove McpServerConfigForProcessTransport è McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig.

`SettingSource`

Controlla quali fonti di configurazione basate su filesystem l’SDK carica le impostazioni da.

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

Valore	Descrizione	Posizione
`'user'`	Impostazioni globali dell’utente	`~/.claude/settings.json`
`'project'`	Impostazioni del progetto condivise (controllate dalla versione)	`.claude/settings.json`
`'local'`	Impostazioni del progetto locale (gitignorate)	`.claude/settings.local.json`

Comportamento predefinito

Quando settingSources è omesso o undefined, query() carica le stesse impostazioni del filesystem del CLI Claude Code: utente, progetto e locale. Le impostazioni della politica gestita vengono caricate in tutti i casi. Vedi Cosa settingSources non controlla per gli input che vengono letti indipendentemente da questa opzione, e come disabilitarli.

Perché usare settingSources

Disabilita le impostazioni del filesystem:

// Non caricare le impostazioni utente, progetto o locali dal disco
const result = query({
  prompt: "Analyze this code",
  options: { settingSources: [] }
});

Carica tutte le impostazioni del filesystem esplicitamente:

const result = query({
  prompt: "Analyze this code",
  options: {
    settingSources: ["user", "project", "local"] // Carica tutte le impostazioni
  }
});

Carica solo fonti di impostazioni specifiche:

// Carica solo le impostazioni del progetto, ignora utente e locale
const result = query({
  prompt: "Run CI checks",
  options: {
    settingSources: ["project"] // Solo .claude/settings.json
  }
});

Ambienti di test e CI:

// Assicura un comportamento coerente in CI escludendo le impostazioni locali
const result = query({
  prompt: "Run tests",
  options: {
    settingSources: ["project"], // Solo impostazioni condivise dal team
    permissionMode: "bypassPermissions"
  }
});

Applicazioni solo SDK:

// Definisci tutto a livello di programmazione.
// Passa [] per rinunciare alle fonti di impostazioni del filesystem.
const result = query({
  prompt: "Review this PR",
  options: {
    settingSources: [],
    agents: {
      /* ... */
    },
    mcpServers: {
      /* ... */
    },
    allowedTools: ["Read", "Grep", "Glob"]
  }
});

Caricamento delle istruzioni del progetto CLAUDE.md:

// Carica le impostazioni del progetto per includere i file CLAUDE.md
const result = query({
  prompt: "Add a new feature following project conventions",
  options: {
    systemPrompt: {
      type: "preset",
      preset: "claude_code" // Usa il prompt di sistema di Claude Code
    },
    settingSources: ["project"], // Carica CLAUDE.md dalla directory del progetto
    allowedTools: ["Read", "Write", "Edit"]
  }
});

Precedenza delle impostazioni

Quando più fonti vengono caricate, le impostazioni vengono unite con questa precedenza (più alta a più bassa):

Impostazioni locali (.claude/settings.local.json)
Impostazioni del progetto (.claude/settings.json)
Impostazioni dell’utente (~/.claude/settings.json)

Le opzioni programmatiche come agents e allowedTools sovrascrivono le impostazioni del filesystem utente, progetto e locale. Le impostazioni della politica gestita hanno precedenza sulle opzioni programmatiche.

`PermissionMode`

type PermissionMode =
  | "default" // Comportamento di permesso standard
  | "acceptEdits" // Auto-accetta le modifiche ai file
  | "bypassPermissions" // Bypass di tutti i controlli di permesso
  | "plan" // Modalità di pianificazione - nessuna esecuzione
  | "dontAsk" // Non richiedere i permessi, nega se non pre-approvato
  | "auto"; // Usa un classificatore di modello per approvare o negare ogni chiamata di tool

`CanUseTool`

Tipo di funzione di permesso personalizzato per controllare l’uso dei tool.

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

Opzione	Tipo	Descrizione
`signal`	`AbortSignal`	Segnalato se l’operazione deve essere interrotta
`suggestions`	`PermissionUpdate[]`	Aggiornamenti di permesso suggeriti in modo che l’utente non venga richiesto di nuovo per questo tool
`blockedPath`	`string`	Il percorso del file che ha attivato la richiesta di permesso, se applicabile
`decisionReason`	`string`	Spiega perché questa richiesta di permesso è stata attivata
`toolUseID`	`string`	Identificatore univoco per questa specifica chiamata di tool all’interno del messaggio dell’assistente
`agentID`	`string`	Se in esecuzione all’interno di un sub-agente, l’ID del sub-agente

`PermissionResult`

Risultato di un controllo di permesso.

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

`ToolConfig`

Configurazione per il comportamento dei tool incorporati.

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

Campo	Tipo	Descrizione
`askUserQuestion.previewFormat`	`'markdown' \| 'html'`	Acconsente al campo `preview` su `AskUserQuestion` opzioni e imposta il suo formato di contenuto. Se non impostato, Claude non emette anteprime

`McpServerConfig`

Configurazione per i 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`

Configurazione per il caricamento dei plugin nell’SDK.

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

Campo	Tipo	Descrizione
`type`	`'local'`	Deve essere `'local'` (attualmente supportati solo plugin locali)
`path`	`string`	Percorso assoluto o relativo alla directory del plugin

Esempio:

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

Per informazioni complete sulla creazione e l’uso dei plugin, vedi Plugins.

Tipi di messaggio

`SDKMessage`

Tipo di unione di tutti i possibili messaggi restituiti dalla 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`

Messaggio di risposta dell’assistente.

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

Il campo message è un BetaMessage dall’SDK Anthropic. Include campi come id, content, model, stop_reason e usage. SDKAssistantMessageError è uno di: 'authentication_failed', 'billing_error', 'rate_limit', 'invalid_request', 'server_error', 'max_output_tokens', o 'unknown'.

`SDKUserMessage`

Messaggio di input dell’utente.

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

Imposta shouldQuery a false per aggiungere il messaggio alla trascrizione senza attivare un turno dell’assistente. Il messaggio viene mantenuto e unito al prossimo messaggio utente che attiva un turno. Usa questo per iniettare contesto, come l’output di un comando che hai eseguito fuori banda, senza spendere una chiamata di modello su di esso.

`SDKUserMessageReplay`

Messaggio utente riprodotto con UUID obbligatorio.

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`

Messaggio di risultato finale.

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`

Messaggio di inizializzazione del sistema.

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`

Messaggio parziale di streaming (solo quando includePartialMessages è true).

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

`SDKCompactBoundaryMessage`

Messaggio che indica un limite di compattazione della conversazione.

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

`SDKPluginInstallMessage`

Evento di progresso dell’installazione del plugin. Emesso quando CLAUDE_CODE_SYNC_PLUGIN_INSTALL è impostato, in modo che la tua applicazione Agent SDK possa tracciare l’installazione del plugin del marketplace prima del primo turno. Gli stati started e completed racchiudono l’installazione complessiva. Gli stati installed e failed segnalano i singoli marketplace e includono name.

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

`SDKPermissionDenial`

Informazioni su un uso di tool negato.

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

Tipi di hook

Per una guida completa sull’uso degli hook con esempi e pattern comuni, vedi la guida Hooks.

`HookEvent`

Eventi hook disponibili.

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

`HookCallback`

Tipo di funzione callback hook.

type HookCallback = (
  input: HookInput, // Unione di tutti i tipi di input hook
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;

`HookCallbackMatcher`

Configurazione hook con matcher opzionale.

interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
  timeout?: number; // Timeout in secondi per tutti gli hook in questo matcher
}

`HookInput`

Tipo di unione di tutti i tipi di input hook.

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

`BaseHookInput`

Interfaccia base che tutti i tipi di input hook estendono.

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; // Stringa dall'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`

Valore di ritorno 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;
            };
      };
};

Tipi di input dei tool

Documentazione degli schemi di input per tutti i tool Claude Code incorporati. Questi tipi vengono esportati da @anthropic-ai/claude-agent-sdk e possono essere usati per le interazioni dei tool type-safe.

`ToolInputSchemas`

Unione di tutti i tipi di input dei tool, esportati da @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

Nome del tool: Agent (precedentemente Task, che è ancora accettato come 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";
};

Avvia un nuovo agente per gestire compiti complessi e multi-step in modo autonomo.

AskUserQuestion

Nome del tool: AskUserQuestion

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

Pone domande di chiarimento all’utente durante l’esecuzione. Vedi Gestisci approvazioni e input dell’utente per i dettagli di utilizzo.

Bash

Nome del tool: Bash

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

Esegue comandi bash in una sessione shell persistente con timeout opzionale ed esecuzione in background.

Monitor

Nome del tool: Monitor

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

Esegue uno script di background e consegna ogni riga stdout a Claude come evento in modo che possa reagire senza polling. Imposta persistent: true per i watch di lunghezza della sessione come code tail. Monitor segue le stesse regole di permesso di Bash. Vedi il riferimento del tool Monitor per il comportamento e la disponibilità del provider.

TaskOutput

Nome del tool: TaskOutput

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

Recupera l’output da un’attività di background in esecuzione o completata.

Edit

Nome del tool: Edit

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

Esegue sostituzioni di stringhe esatte nei file.

Read

Nome del tool: Read

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

Legge i file dal filesystem locale, inclusi testo, immagini, PDF e notebook Jupyter. Usa pages per gli intervalli di pagine PDF (ad esempio, "1-5").

Write

Nome del tool: Write

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

Scrive un file nel filesystem locale, sovrascrivendo se esiste.

Glob

Nome del tool: Glob

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

Corrispondenza di pattern di file veloce che funziona con qualsiasi dimensione di codebase.

Grep

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

Potente tool di ricerca costruito su ripgrep con supporto regex.

TaskStop

Nome del tool: TaskStop

type TaskStopInput = {
  task_id?: string;
  shell_id?: string; // Deprecato: usa task_id
};

Interrompe un’attività di background o shell in esecuzione per ID.

NotebookEdit

Nome del tool: NotebookEdit

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

Modifica le celle nei file dei notebook Jupyter.

WebFetch

Nome del tool: WebFetch

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

Recupera il contenuto da un URL e lo elabora con un modello AI.

WebSearch

Nome del tool: WebSearch

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

Cerca il web e restituisce risultati formattati.

TodoWrite

Nome del tool: TodoWrite

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

Crea e gestisce un elenco di attività strutturato per il tracciamento del progresso.

ExitPlanMode

Nome del tool: ExitPlanMode

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

Esce dalla modalità di pianificazione. Facoltativamente specifica i permessi basati su prompt necessari per implementare il piano.

ListMcpResources

Nome del tool: ListMcpResources

type ListMcpResourcesInput = {
  server?: string;
};

Elenca le risorse MCP disponibili dai server connessi.

ReadMcpResource

Nome del tool: ReadMcpResource

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

Legge una risorsa MCP specifica da un server.

Config

Nome del tool: Config

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

Ottiene o imposta un valore di configurazione.

EnterWorktree

Nome del tool: EnterWorktree

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

Crea e entra in un worktree git temporaneo per il lavoro isolato. Passa path per passare a un worktree esistente del repository corrente invece di crearne uno nuovo. name e path si escludono a vicenda.

Tipi di output dei tool

Documentazione degli schemi di output per tutti i tool Claude Code incorporati. Questi tipi vengono esportati da @anthropic-ai/claude-agent-sdk e rappresentano i dati di risposta effettivi restituiti da ogni tool.

`ToolOutputSchemas`

Unione di tutti i tipi di output dei tool.

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

Agent

Nome del tool: Agent (precedentemente Task, che è ancora accettato come 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;
    };

Restituisce il risultato dal subagente. Discriminato sul campo status: "completed" per le attività finite, "async_launched" per le attività di background, e "sub_agent_entered" per i subagenti interattivi.

AskUserQuestion

Nome del tool: AskUserQuestion

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

Restituisce le domande poste e le risposte dell’utente.

Bash

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

Restituisce l’output del comando con stdout/stderr divisi. I comandi di background includono un backgroundTaskId.

Monitor

Nome del tool: Monitor

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

Restituisce l’ID dell’attività di background per il monitor in esecuzione. Usa questo ID con TaskStop per annullare il watch in anticipo.

Edit

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

Restituisce il diff strutturato dell’operazione di modifica.

Read

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

Restituisce il contenuto del file in un formato appropriato al tipo di file. Discriminato sul campo type.

Write

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

Restituisce il risultato della scrittura con informazioni sul diff strutturato.

Glob

Nome del tool: Glob

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

Restituisce i percorsi dei file che corrispondono al pattern glob, ordinati per tempo di modifica.

Grep

Nome del tool: Grep

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

Restituisce i risultati della ricerca. La forma varia in base a mode: elenco di file, contenuto con corrispondenze o conteggi di corrispondenze.

TaskStop

Nome del tool: TaskStop

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

Restituisce la conferma dopo l’interruzione dell’attività di background.

NotebookEdit

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

Restituisce il risultato della modifica del notebook con i contenuti del file originale e aggiornato.

WebFetch

Nome del tool: WebFetch

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

Restituisce il contenuto recuperato con lo stato HTTP e i metadati.

WebSearch

Nome del tool: WebSearch

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

Restituisce i risultati della ricerca dal web.

TodoWrite

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

Restituisce gli elenchi di attività precedenti e aggiornati.

ExitPlanMode

Nome del tool: ExitPlanMode

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

Restituisce lo stato del piano dopo l’uscita dalla modalità di pianificazione.

ListMcpResources

Nome del tool: ListMcpResources

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

Restituisce un array di risorse MCP disponibili.

ReadMcpResource

Nome del tool: ReadMcpResource

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

Restituisce i contenuti della risorsa MCP richiesta.

Config

Nome del tool: Config

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

Restituisce il risultato di un’operazione di configurazione get o set.

EnterWorktree

Nome del tool: EnterWorktree

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

Restituisce le informazioni sul worktree git.

Tipi di permesso

`PermissionUpdate`

Operazioni per l’aggiornamento dei permessi.

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" // Impostazioni globali dell'utente
  | "projectSettings" // Impostazioni del progetto per directory
  | "localSettings" // Impostazioni locali gitignorate
  | "session" // Solo sessione corrente
  | "cliArg"; // Argomento CLI

`PermissionRuleValue`

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

Altri tipi

`ApiKeySource`

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

`SdkBeta`

Funzioni beta disponibili che possono essere abilitate tramite l’opzione betas. Vedi Intestazioni beta per ulteriori informazioni.

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

La beta context-1m-2025-08-07 è ritirata a partire dal 30 aprile 2026. Passare questo valore con Claude Sonnet 4.5 o Sonnet 4 non ha effetto, e le richieste che superano la finestra di contesto standard di 200k token restituiscono un errore. Per usare una finestra di contesto di 1M token, esegui la migrazione a Claude Sonnet 4.6, Claude Opus 4.6, o Claude Opus 4.7, che includono 1M di contesto ai prezzi standard senza intestazione beta richiesta.

`SlashCommand`

Informazioni su un comando slash disponibile.

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

`ModelInfo`

Informazioni su un modello disponibile.

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

`AgentInfo`

Informazioni su un subagente disponibile che può essere invocato tramite il tool Agent.

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

Campo	Tipo	Descrizione
`name`	`string`	Identificatore del tipo di agente (ad esempio, `"Explore"`, `"general-purpose"`)
`description`	`string`	Descrizione di quando usare questo agente
`model`	`string \| undefined`	Alias del modello che questo agente usa. Se omesso, eredita il modello del genitore

`McpServerStatus`

Stato di un server MCP connesso.

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`

La configurazione di un server MCP come segnalato da mcpServerStatus(). Questa è l’unione di tutti i tipi di trasporto del server MCP.

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

Vedi McpServerConfig per i dettagli su ogni tipo di trasporto.

`AccountInfo`

Informazioni sull’account per l’utente autenticato.

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

`ModelUsage`

Statistiche di utilizzo per modello restituite nei messaggi di risultato. Il valore costUSD è una stima lato client. Vedi Traccia costo e utilizzo per le avvertenze di fatturazione.

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`

Una versione di Usage con tutti i campi nullable resi non-nullable.

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

`Usage`

Statistiche di utilizzo dei token (da @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`

Tipo di risultato del tool MCP (da @modelcontextprotocol/sdk/types.js).

type CallToolResult = {
  content: Array<{
    type: "text" | "image" | "resource";
    // I campi aggiuntivi variano in base al tipo
  }>;
  isError?: boolean;
};

`ThinkingConfig`

Controlla il comportamento di pensiero/ragionamento di Claude. Ha precedenza sul deprecato maxThinkingTokens.

type ThinkingConfig =
  | { type: "adaptive" } // Il modello determina quando e quanto ragionare (Opus 4.6+)
  | { type: "enabled"; budgetTokens?: number } // Budget di token di pensiero fisso
  | { type: "disabled" }; // Nessun pensiero esteso

`SpawnedProcess`

Interfaccia per la generazione di processi personalizzati (usata con l’opzione spawnClaudeCodeProcess). ChildProcess soddisfa già questa interfaccia.

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`

Opzioni passate alla funzione di generazione personalizzata.

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

`McpSetServersResult`

Risultato di un’operazione setMcpServers().

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

`RewindFilesResult`

Risultato di un’operazione rewindFiles().

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

`SDKStatusMessage`

Messaggio di aggiornamento dello stato (ad esempio, compattazione).

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

`SDKTaskNotificationMessage`

Notifica quando un’attività di background si completa, fallisce o viene interrotta. Le attività di background includono i comandi Bash run_in_background, i watch Monitor e i subagenti di background.

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`

Riepilogo dell’uso dei tool in una conversazione.

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

`SDKHookStartedMessage`

Emesso quando un hook inizia l’esecuzione.

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

`SDKHookProgressMessage`

Emesso mentre un hook è in esecuzione, con 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`

Emesso quando un hook finisce l’esecuzione.

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`

Emesso periodicamente mentre un tool è in esecuzione per indicare il progresso.

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`

Emesso durante i flussi di autenticazione.

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

`SDKTaskStartedMessage`

Emesso quando un’attività di background inizia. Il campo task_type è "local_bash" per i comandi Bash di background e i watch Monitor, "local_agent" per i subagenti, o "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`

Emesso periodicamente mentre un’attività di background è in esecuzione.

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`

Emesso quando i checkpoint dei file vengono persistiti su disco.

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`

Emesso quando la sessione incontra un limite di velocità.

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 da un comando slash locale (ad esempio, /voice o /cost). Visualizzato come testo in stile assistente nella trascrizione.

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

`SDKPromptSuggestionMessage`

Emesso dopo ogni turno quando promptSuggestions è abilitato. Contiene un prompt utente successivo previsto.

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

`AbortError`

Classe di errore personalizzata per le operazioni di interruzione.

class AbortError extends Error {}

Configurazione della sandbox

`SandboxSettings`

Configurazione per il comportamento della sandbox. Usa questo per abilitare il sandboxing dei comandi e configurare le restrizioni di rete a livello di programmazione.

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

Proprietà	Tipo	Predefinito	Descrizione
`enabled`	`boolean`	`false`	Abilita la modalità sandbox per l’esecuzione dei comandi
`autoAllowBashIfSandboxed`	`boolean`	`true`	Auto-approva i comandi bash quando la sandbox è abilitata
`excludedCommands`	`string[]`	`[]`	Comandi che sempre bypassano le restrizioni della sandbox (ad esempio, `['docker']`). Questi vengono eseguiti senza sandbox automaticamente senza coinvolgimento del modello
`allowUnsandboxedCommands`	`boolean`	`true`	Consenti al modello di richiedere l’esecuzione di comandi al di fuori della sandbox. Quando `true`, il modello può impostare `dangerouslyDisableSandbox` nell’input del tool, che ricade nel sistema di permessi
`network`	`SandboxNetworkConfig`	`undefined`	Configurazione della sandbox specifica della rete
`filesystem`	`SandboxFilesystemConfig`	`undefined`	Configurazione della sandbox specifica del filesystem per le restrizioni di lettura/scrittura
`ignoreViolations`	`Record<string, string[]>`	`undefined`	Mappa delle categorie di violazione ai pattern da ignorare (ad esempio, `{ file: ['/tmp/*'], network: ['localhost'] }`)
`enableWeakerNestedSandbox`	`boolean`	`false`	Abilita una sandbox nidificata più debole per la compatibilità
`ripgrep`	`{ command: string; args?: string[] }`	`undefined`	Configurazione del binario ripgrep personalizzato per gli ambienti sandbox

Esempio di utilizzo

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

Sicurezza del socket Unix: L’opzione allowUnixSockets può concedere l’accesso a potenti servizi di sistema. Ad esempio, consentire /var/run/docker.sock concede effettivamente l’accesso completo al sistema host tramite l’API Docker, bypassando l’isolamento della sandbox. Consenti solo i socket Unix strettamente necessari e comprendi le implicazioni di sicurezza di ciascuno.

`SandboxNetworkConfig`

Configurazione specifica della rete per la modalità sandbox.

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

Proprietà	Tipo	Predefinito	Descrizione
`allowedDomains`	`string[]`	`[]`	Nomi di dominio a cui i processi in sandbox possono accedere
`deniedDomains`	`string[]`	`[]`	Nomi di dominio a cui i processi in sandbox non possono accedere. Ha la precedenza su `allowedDomains`
`allowManagedDomainsOnly`	`boolean`	`false`	Limita l’accesso di rete solo ai domini in `allowedDomains`
`allowLocalBinding`	`boolean`	`false`	Consenti ai processi di associarsi alle porte locali (ad esempio, per i server di sviluppo)
`allowUnixSockets`	`string[]`	`[]`	Percorsi dei socket Unix a cui i processi possono accedere (ad esempio, socket Docker)
`allowAllUnixSockets`	`boolean`	`false`	Consenti l’accesso a tutti i socket Unix
`httpProxyPort`	`number`	`undefined`	Porta del proxy HTTP per le richieste di rete
`socksProxyPort`	`number`	`undefined`	Porta del proxy SOCKS per le richieste di rete

`SandboxFilesystemConfig`

Configurazione specifica del filesystem per la modalità sandbox.

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

Proprietà	Tipo	Predefinito	Descrizione
`allowWrite`	`string[]`	`[]`	Pattern di percorso file per consentire l’accesso in scrittura a
`denyWrite`	`string[]`	`[]`	Pattern di percorso file per negare l’accesso in scrittura a
`denyRead`	`string[]`	`[]`	Pattern di percorso file per negare l’accesso in lettura a

Fallback dei permessi per i comandi senza sandbox

Quando allowUnsandboxedCommands è abilitato, il modello può richiedere di eseguire comandi al di fuori della sandbox impostando dangerouslyDisableSandbox: true nell’input del tool. Queste richieste ricadono nel sistema di permessi esistente, il che significa che il tuo handler canUseTool viene invocato, permettendoti di implementare la logica di autorizzazione personalizzata.

excludedCommands vs allowUnsandboxedCommands:

excludedCommands: Un elenco statico di comandi che sempre bypassano la sandbox automaticamente (ad esempio, ['docker']). Il modello non ha controllo su questo.
allowUnsandboxedCommands: Consenti al modello di decidere in fase di esecuzione se richiedere l’esecuzione senza sandbox impostando dangerouslyDisableSandbox: true nell’input del 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 // Il modello può richiedere l'esecuzione senza sandbox
    },
    permissionMode: "default",
    canUseTool: async (tool, input) => {
      // Controlla se il modello sta richiedendo di bypassare la sandbox
      if (tool === "Bash" && input.dangerouslyDisableSandbox) {
        // Il modello sta richiedendo di eseguire questo comando al di fuori della 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);
}

Questo pattern ti consente di:

Controllare le richieste del modello: Registra quando il modello richiede l’esecuzione senza sandbox
Implementare allowlist: Consenti solo comandi specifici di essere eseguiti senza sandbox
Aggiungere flussi di lavoro di approvazione: Richiedi l’autorizzazione esplicita per le operazioni privilegiate

I comandi in esecuzione con dangerouslyDisableSandbox: true hanno accesso completo al sistema. Assicurati che il tuo handler canUseTool convalidi queste richieste attentamente.Se permissionMode è impostato su bypassPermissions e allowUnsandboxedCommands è abilitato, il modello può autonomamente eseguire comandi al di fuori della sandbox senza alcun prompt di approvazione. Questa combinazione consente effettivamente al modello di sfuggire all’isolamento della sandbox silenziosamente.

Vedi anche

Panoramica dell’SDK - Concetti generali dell’SDK
Riferimento Python SDK - Documentazione dell’SDK Python
Riferimento CLI - Interfaccia della riga di comando
Flussi di lavoro comuni - Guide passo dopo passo

Agent SDK

Concetti fondamentali

Input e output

Estendi con strumenti

Personalizza il comportamento

Controllo e osservabilità

Distribuzione

Riferimenti SDK

​Installazione

​Funzioni

​query()

​Parametri

​Restituisce

​startup()

​Parametri

​Restituisce

​Esempio

​tool()

​Parametri

​ToolAnnotations

​createSdkMcpServer()

​Parametri

​listSessions()

​Parametri

​Tipo di ritorno: SDKSessionInfo

​Esempio

​getSessionMessages()

​Parametri

​Tipo di ritorno: SessionMessage

​Esempio

​getSessionInfo()

​Parametri

​renameSession()

​Parametri

​tagSession()

​Parametri

​Tipi

​Options

​Oggetto Query

​Metodi

​WarmQuery

​Metodi

​SDKControlInitializeResponse

​AgentDefinition

​AgentMcpServerSpec

​SettingSource

​Comportamento predefinito

​Perché usare settingSources

​Precedenza delle impostazioni

​PermissionMode

​CanUseTool

​PermissionResult

​ToolConfig

​McpServerConfig

​McpStdioServerConfig

​McpSSEServerConfig

​McpHttpServerConfig

​McpSdkServerConfigWithInstance

​McpClaudeAIProxyServerConfig

​SdkPluginConfig

​Tipi di messaggio

​SDKMessage

​SDKAssistantMessage

​SDKUserMessage

​SDKUserMessageReplay

​SDKResultMessage

​SDKSystemMessage

​SDKPartialAssistantMessage

​SDKCompactBoundaryMessage

​SDKPluginInstallMessage

​SDKPermissionDenial

​Tipi di hook

​HookEvent

​HookCallback

​HookCallbackMatcher

​HookInput

​BaseHookInput

​PreToolUseHookInput

​PostToolUseHookInput

​PostToolUseFailureHookInput

Installazione

Funzioni

`query()`

Parametri

Restituisce

`startup()`

Parametri

Restituisce

Esempio

`tool()`

Parametri

`ToolAnnotations`

`createSdkMcpServer()`

Parametri

`listSessions()`

Parametri

Tipo di ritorno: `SDKSessionInfo`

Esempio

`getSessionMessages()`

Parametri

Tipo di ritorno: `SessionMessage`

Esempio

`getSessionInfo()`

Parametri

`renameSession()`

Parametri

`tagSession()`

Parametri

Tipi

`Options`

Oggetto `Query`

Metodi

`WarmQuery`

Metodi

`SDKControlInitializeResponse`

`AgentDefinition`

`AgentMcpServerSpec`

`SettingSource`

Comportamento predefinito

Perché usare settingSources

Precedenza delle impostazioni

`PermissionMode`

`CanUseTool`

`PermissionResult`

`ToolConfig`

`McpServerConfig`

`McpStdioServerConfig`

`McpSSEServerConfig`

`McpHttpServerConfig`

`McpSdkServerConfigWithInstance`

`McpClaudeAIProxyServerConfig`

`SdkPluginConfig`

Tipi di messaggio

`SDKMessage`

`SDKAssistantMessage`

`SDKUserMessage`

`SDKUserMessageReplay`

`SDKResultMessage`

`SDKSystemMessage`

`SDKPartialAssistantMessage`

`SDKCompactBoundaryMessage`

`SDKPluginInstallMessage`

`SDKPermissionDenial`

Tipi di hook

`HookEvent`

`HookCallback`

`HookCallbackMatcher`

`HookInput`

`BaseHookInput`

`PreToolUseHookInput`

`PostToolUseHookInput`

`PostToolUseFailureHookInput`

`NotificationHookInput`

`UserPromptSubmitHookInput`

`SessionStartHookInput`

`SessionEndHookInput`

`StopHookInput`

`SubagentStartHookInput`

`SubagentStopHookInput`

`PreCompactHookInput`