Riferimento Agent SDK - TypeScript

​

Installazione

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

​

Compilare in un singolo eseguibile

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

const cliPath = extractFromBunfs(binPath);

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

• Per la compilazione incrociata, installa il pacchetto della piattaforma non corrispondente, ad esempio npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force.
• Su Windows, il sottopercorso binario è claude.exe, ad esempio @anthropic-ai/claude-agent-sdk-win32-x64/claude.exe.

​

Importa l’entry /core quando raggruppi l’Agent SDK

​

Funzioni

​

query()

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

​

Parametri

​

Restituisce

​

startup()

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

​

Parametri

​

Restituisce

​

Esempio

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

​

prewarm()

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

​

Esempio

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

// All'avvio dell'applicazione, prima che la cartella della sessione sia nota
const spare = await prewarm({ options: { maxTurns: 3 } });

// Più tardi, quando l'utente avvia una sessione in una cartella
const claimedQuery = spare.claim({
  prompt: "What files are here?",
  options: { cwd: "/path/to/project" },
});

spare.claimed.catch((error: Error) => {
  // A meno che il messaggio non inizi con "option_not_applied", il prompt non è stato eseguito:
  // avvia questa sessione con query() invece
  console.error("Claim failed:", error.message);
});

try {
  for await (const message of claimedQuery) {
    console.log(message);
  }
} catch (error) {
  // Dopo un claim rifiutato, la query rivendicata genera un'eccezione una volta prodotto il risultato di errore
  console.error(`Session ended with an error: ${error}`);
}

​

tool()

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

​

Parametri

​

ToolAnnotations

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

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

​

Parametri

​

listSessions()

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

​

Parametri

​

Tipo di ritorno: SDKSessionInfo

​

Esempio

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

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

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

​

getSessionMessages()

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

​

Parametri

​

Tipo di ritorno: SessionMessage

​

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

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

​

Parametri

​

renameSession()

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

​

Parametri

​

tagSession()

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

​

Parametri

​

forkSession()

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

​

Parametri

• sessionId non è un UUID
• la sessione non viene trovata, o non contiene messaggi
• upToMessageId non corrisponde a nessun messaggio nella trascrizione

​

resolveSettings()

• policyHelper: resolveSettings() legge le fonti MDM, inclusi plist macOS e Windows HKLM/HKCU, ma non esegue il subprocess policyHelper configurato dall’amministratore.
• Impostazioni gestite dal server: resolveSettings() non recupera impostazioni gestite dal server. Passale come options.serverManagedSettings per includerle.
• defaultMode: lo snapshot restituisce permissions.defaultMode così com’è da ogni livello, quindi può includere i valori 'auto' e 'bypassPermissions' dalle impostazioni di progetto e locali, che una sessione live ignora.

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

​

Parametri

​

Tipo di ritorno: ResolvedSettings

​

Esempio

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

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

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

​

Tipi

​

Options

​

Gestire risposte API lente o bloccate

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

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

• API_TIMEOUT_MS: timeout per richiesta sul client Anthropic, in millisecondi. Valore predefinito 600000. Si applica al ciclo principale e a tutti i subagent.
• CLAUDE_CODE_MAX_RETRIES: numero massimo di nuovi tentativi API. Valore predefinito 10, con un limite di 15. Ogni nuovo tentativo ha la propria finestra API_TIMEOUT_MS. Per le esecuzioni non presidiate che devono attendere durante interruzioni più lunghe, imposta CLAUDE_CODE_RETRY_WATCHDOG=1: riprova indefinitamente in caso di errori di capacità transitori e, su Claude Code v2.1.199 o successive, alza il valore predefinito per gli altri errori transitori a 300 e rimuove il limite su questa variabile.
• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: watchdog dei blocchi per i subagent. Mentre il watchdog dello stream è attivo, il valore predefinito è CLAUDE_STREAM_IDLE_TIMEOUT_MS più 5 minuti, ovvero 600000 a meno che tu non aumenti quella variabile. Con il watchdog dello stream disattivato, il valore predefinito è 600000. Prima della v2.1.257, il valore predefinito era sempre 600000. Il timer si azzera a ogni evento dello stream. In caso di blocco, Claude Code interrompe il subagent e segnala il blocco al padre. Per un subagent in background, contrassegna anche l’attività come non riuscita e allega l’eventuale risultato parziale.
• CLAUDE_ENABLE_STREAM_WATCHDOG con CLAUDE_STREAM_IDLE_TIMEOUT_MS: watchdog dello stream che interrompe la richiesta quando gli header sono arrivati ma il corpo della risposta smette di essere trasmesso. Il watchdog è attivo per impostazione predefinita per tutti i provider; imposta CLAUDE_ENABLE_STREAM_WATCHDOG=0 per disabilitarlo. CLAUDE_STREAM_IDLE_TIMEOUT_MS ha come valore predefinito 300000 e non può scendere sotto tale minimo. Dopo l’interruzione, Nuovi tentativi automatici descrive cosa fa Claude Code, in base a quanto era avanzata la risposta. Mentre il watchdog attende una risposta che un gateway dietro ANTHROPIC_BASE_URL mantiene aperta con ping keep-alive, un host che imposta includePartialMessages continua a ricevere eventi dello stream ping, quindi interpreta quei frame come segnali di attività invece di far scadere la sessione per il silenzio. Prima della v2.1.257, i frame si interrompevano 5 minuti dopo l’ultimo evento reale dello stream.

​

Oggetto Query

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

​

Metodi

​

applyFlagSettings()

• Applicate al turno successivo: effortLevel, ultracode, permissions, hooks, skillOverrides, fastMode, agent. Cambiare agent applica al turno successivo anche l’override del modello e gli hook di quell’agente. Il suo prompt di sistema si applica al turno successivo oppure, in una sessione che riutilizza un prompt di sistema registrato, una volta che la sessione viene compattata.
• Applicate durante il turno corrente: model. Se cambi model mentre Claude sta lavorando a un turno, la risposta che Claude sta già generando termina con il vecchio modello, e il resto del turno, a partire dalla chiamata successiva che Claude Code fa al modello, usa quello nuovo. I subagent mantengono il proprio modello. Prima della v2.1.212, un cambio a metà turno attendeva il turno successivo.
• Nessun effetto a metà sessione: le opzioni del prompt di sistema. Vengono risolte una sola volta all’avvio, quindi la sessione in esecuzione mantiene il valore originale anche se la chiamata riesce. Per cambiarle, avvia una nuova sessione.

• effortLevel: null riporta la sessione al livello di sforzo predefinito del modello, non all’opzione effort di query() né a un effortLevel di un file di impostazioni.
• agent: null esegue il thread principale senza agente, a partire dal turno successivo, invece di ripristinare l’opzione agent di query() o un agent di un file di impostazioni. Se l’agente rimosso aveva applicato il proprio modello, la sessione torna al modello risolto all’avvio.
• ultracode: null disattiva ultracode, come fa false, invece di ripristinare un valore ultracode di un file di impostazioni. La sessione mantiene il livello di sforzo corrente, quindi passa effortLevel nella stessa chiamata per cambiarlo.

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

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

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

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

​

updateSettings()

• "localSettings": accetta outputStyle e ne esegue il merge nel file di impostazioni locali del progetto, .claude/settings.local.json. Il nuovo stile ha effetto alla richiesta successiva della sessione.
• "userSettings": accetta effortLevel e lo salva come livello di sforzo predefinito per il modello corrente della sessione, sotto modelSettings nel tuo file di impostazioni utente. Passare max non scrive nulla, perché max vale solo per la sessione. In ogni caso la sessione in esecuzione mantiene il livello di sforzo corrente, quindi chiama applyFlagSettings() quando vuoi cambiare anche quello. Questa fonte richiede TypeScript SDK v0.3.277 o successivo, che include Claude Code v2.1.277.

​

toggleMcpServer()

• Un server stdio, SSE o HTTP aggiunto a metà sessione con setMcpServers(): la rimozione dei suoi strumenti richiede Claude Code v2.1.285 o successivo.
• Un server in-process creato con createSdkMcpServer(), che tu lo abbia passato in mcpServers o con setMcpServers(): la sua disconnessione e la rimozione dei suoi strumenti richiedono Claude Code v2.1.286 o successivo. Disabilitarne uno fa inoltre fallire le sue chiamate agli strumenti ancora in esecuzione, così Claude riceve immediatamente un risultato di errore per ciascuna di esse, senza attendere che il tuo handler restituisca un valore.

​

WarmQuery

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

​

Metodi

​

SpareProcess

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

​

Membri

​

SDKControlInitializeResponse

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

• true: Claude Code ha registrato gli hook. Il primo initialize di una sessione restituisce questo valore. Anche un initialize ripetuto inviato tramite lo stdin della CLI restituisce true. In quel caso gli hook della nuova richiesta sostituiscono quelli registrati in precedenza.
• false: Claude Code ha ignorato gli hook. Un initialize ripetuto inviato a una sessione remota restituisce questo valore, così un secondo client che si unisce a una sessione non può sostituire gli hook registrati dal primo client.

• Il campo richiede Agent SDK v0.3.296 o successiva, che include Claude Code v2.1.296.
• Se il campo è undefined e hai impostato pathToClaudeCodeExecutable, puntalo a Claude Code v2.1.296 o successiva.

​

SDKControlInterruptResponse

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

• Compaiono solo i messaggi accodati con un UUID. Un array vuoto non significa che non verrà eseguito nient’altro.
• Vengono elencati solo i messaggi del thread principale. I messaggi indirizzati a un subagent non sono inclusi.
• L’elenco può includere UUID che il tuo client non ha mai inviato, come i trigger delle attività pianificate. Ignora gli UUID che non riconosci invece di trattarli come un errore.

​

SDKControlGetContextUsageResponse

• 'full': il valore predefinito. Claude Code conta ogni categoria con richieste API di conteggio dei token. Queste richieste non compaiono nel flusso dei messaggi, quindi un tracciamento dei costi basato sul flusso non le vede. Sull’API Anthropic, il conteggio dei token non viene addebitato.
• 'summary': passa { detail: 'summary' } per ottenere invece una risposta basata sull’utilizzo dell’ultima risposta e su stime locali. Non viene inviata alcuna richiesta di conteggio dei token, e i numeri per categoria sono approssimativi.

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

• categories contiene i totali per categoria. Il campo kind di ogni voce classifica la riga con gli stessi valori di SDKContextUsageCategory. Classifica le righe in base a questo campo anziché al name visualizzato. Il campo richiede Agent SDK v0.3.268 o successivo.
• mcpTools e agents attribuiscono i token ai singoli strumenti MCP e ai subagent.
• memoryFiles elenca ogni file di memoria caricato con il relativo costo.
• skills.skillFrontmatter attribuisce i token dell’elenco delle skill a ciascuna skill inclusa. I conteggi per skill misurano la voce di elenco di ciascuna skill così come Claude Code la invia effettivamente, che può essere più breve del frontmatter completo della skill. Confronta skills.totalSkills con skills.includedSkills per verificare se ogni skill rilevata è stata inclusa nell’elenco.

​

SDKControlReadFileResponse

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

​

Cosa può leggere readFile()

• Un file regolare all’interno di una delle directory di lavoro della sessione, come cwd e additionalDirectories
• Alcuni file propri di Claude Code per la sessione, come i risultati degli strumenti

​

SDKControlReloadPluginsResponse

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

• commands, agents e mcpServers: i comandi, i subagent e lo stato dei server MCP della sessione, nelle stesse forme restituite da supportedCommands(), supportedAgents() e mcpServerStatus(). supportedAgents() continua a restituire l’elenco acquisito all’inizializzazione, quindi leggi agents qui per ottenere l’insieme dopo un ricaricamento
• plugins: ogni plugin caricato con il suo name e il path di installazione. version ripete quanto dichiarato nel manifest del plugin ed è controllato dall’autore del plugin, quindi convalidalo prima di considerarlo attendibile. Viene omesso quando il manifest non ne dichiara alcuno
• error_count: il numero di errori durante il caricamento dei plugin

• true: il ricaricamento non è stato applicato, e i campi di tipo collezione descrivono la sessione così com’è ancora. cache_impact indica cosa cambierebbe applicandolo. Per applicarlo comunque, chiama di nuovo reloadPlugins() senza l’opzione.
• false: il controllo non ha rilevato alcun impatto sulla cache, e il ricaricamento è stato applicato.
• Assente: non hai passato l’opzione, oppure l’eseguibile di Claude Code è precedente alla v2.1.268 e ha applicato il ricaricamento.

​

SDKControlReloadSkillsResponse

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

​

SDKControlReloadOutputStylesResponse

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

​

SDKControlMcpReadResourceResponse

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

​

AgentDefinition

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

​

AgentMcpServerSpec

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

​

SettingSource

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

​

Comportamento predefinito

​

Perché usare settingSources

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

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

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

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

​

Precedenza delle impostazioni

1. Impostazioni locali (.claude/settings.local.json)
2. Impostazioni di progetto (.claude/settings.json)
3. Impostazioni utente (~/.claude/settings.json)

​

PermissionMode

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

​

CanUseTool

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

​

PermissionResult

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

​

ToolConfig

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

​

McpServerConfig

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;
  timeout?: number;
  instance: McpServer;
};

​

McpClaudeAIProxyServerConfig

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

​

SdkPluginConfig

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

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

​

Tipi di messaggio

​

SDKMessage

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

​

SDKAssistantMessage

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

• 'model_not_found': il modello selezionato non esiste o non è disponibile per il tuo account o deploy
• 'overloaded': l’API ha restituito un 529 perché il server è al massimo della capacità, a differenza di 'rate_limit', che è un 429 rispetto alla tua quota
• 'account_on_hold': il tuo account è in sospeso
• 'cloud_credential_error': Claude Code non è riuscito a ottenere credenziali AWS o Google Cloud utilizzabili sulla macchina su cui viene eseguito, quindi nessuna richiesta ha raggiunto il provider cloud. La causa abituale è un accesso al cloud scaduto o mai completato su quella macchina, anche se un servizio di credenziali brevemente irraggiungibile segnala lo stesso valore. Consulta Impossibile caricare le credenziali AWS o Google Cloud. Richiede TypeScript Agent SDK v0.3.267 o successivo, che include Claude Code v2.1.267

• La sessione si autentica con una credenziale claude.ai
• La credenziale mostra un tipo di piano noto o include lo scope user:profile
• L’account non usa la fatturazione basata sull’utilizzo

​

SDKUserMessage

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

• pasted_content: se le voci più i blocchi di contenuto al loro interno sono più di 1.000, Claude Code ignora l’intero campo.
• inline_pastes: Claude Code usa le prime 100 voci non vuote e ignora le restanti.

• shouldQuery: impostalo a false per aggiungere il messaggio alla trascrizione senza attivare un turno dell’assistente. Il messaggio viene trattenuto e unito al successivo messaggio utente che attiva un turno. Usalo per iniettare contesto, come l’output di un comando che hai eseguito fuori banda, senza spendere una chiamata al modello.
• client_composed: impostalo a true per fare in modo che Claude Code consegni il testo del messaggio così come è scritto. Claude Code allora non espande le menzioni @path o @server:resource, e non esegue come comando il testo che inizia con /. Mentre l’opzione verbatimPrompts è attiva, l’SDK imposta il campo su ogni messaggio. Richiede TypeScript Agent SDK v0.3.280 o successivo e Claude Code v2.1.248 o successivo.
• priority: controlla quando un messaggio che invii durante un turno in esecuzione raggiunge Claude:
  • 'next', o nessun campo priority: Claude legge il messaggio nello stesso turno, non appena terminano le chiamate agli strumenti in esecuzione. Se il turno termina prima, il messaggio avvia il turno successivo.
  • 'later': Claude Code trattiene il messaggio fino alla fine del turno e lo invia come nuovo turno.
  • 'now' con origin: { kind: "human" }: su Claude Code v2.1.286 o successiva, il lavoro che può proseguire in background viene spostato lì e Claude legge il messaggio nello stesso turno. Il lavoro che può essere spostato include comandi shell, subagent e chiamate agli strumenti MCP. Su v2.1.287 o successiva include anche le chiamate a WebFetch e WebSearch. Quando Claude sta solo scrivendo una risposta, o il lavoro in esecuzione non può essere spostato, Claude Code interrompe invece il turno e Claude legge il messaggio subito dopo.
  • 'now' senza quell’origine: Claude Code interrompe il turno e Claude legge il messaggio subito dopo.

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

• Lo strumento Agent: tool_use_result è AgentOutput. Esegui il rendering a partire da esso anziché analizzare il testo di tool_result. Il content di un risultato completed contiene il report del subagent oppure, per un subagent il cui report passa attraverso una chiamata allo strumento SubagentHandback, una breve nota su quella restituzione al posto del report. In modalità auto su Claude Code v2.1.271 o successiva, ogni subagent che produce un risultato completed riporta in quel modo a meno che non sia un fork, e Claude riceve il report come messaggio separato dal subagent.
• Una chiamata a WebFetch o WebSearch che Claude Code ha spostato in background per consegnare un messaggio 'now': il messaggio dell’utente che contiene il tool_result di quella chiamata ha tool_use_result impostato su { detachedToolCall: true }. La chiamata è ancora in esecuzione e Claude ne riceve il risultato al termine. Non segue un secondo tool_result per quel tool_use_id, quindi se la tua applicazione disegna una riga per ogni chiamata a uno strumento, contrassegna questa riga come spostata in background quando arriva questo messaggio. Richiede Claude Code v2.1.287 o successiva.
• Uno strumento MCP il cui risultato contiene blocchi resource_link: tool_use_result è un oggetto con un array resourceLinks di voci SDKMcpResourceLink. Claude riceve ogni link come una riga di testo nel blocco tool_result, quindi leggi resourceLinks per eseguire il rendering dei file restituiti dal server invece di analizzare quel testo. Claude Code omette resourceLinks quando il risultato non contiene link e nei risultati dei subagent, mantiene al massimo 50 link per risultato e smette di aggiungere link quando l’array raggiunge 64 KiB di JSON serializzato. resourceLinks richiede Agent SDK v0.3.257 o successiva.
• Uno strumento MCP che restituisce structuredContent: tool_use_result è un oggetto il cui membro structuredContent contiene ciò che il server ha inviato e il cui membro content contiene il valore McpOutput. I risultati dei subagent non contengono structuredContent.
• Uno strumento MCP il cui structuredContent serializzato supera 1.048.576 caratteri di JSON: Claude Code omette structuredContent da tool_use_result e imposta al suo posto structuredContentOmitted: true, così la tua applicazione può distinguere un oggetto scartato da uno strumento che non ne ha inviato alcuno. Gli altri membri, come content e resourceLinks, rimangono, e ciò che Claude riceve non cambia. Claude Code v2.1.287 o successiva applica questo limite. Due tipi di strumento fanno eccezione:
  • Gli strumenti dei server SDK in-process sono esenti e consegnano l’oggetto per intero.
  • Uno strumento la cui voce tools/list dichiara una risorsa MCP Apps ui:// ha un limite di 8.388.608 caratteri su Claude Code v2.1.295 o successiva, mentre le versioni precedenti alla v2.1.295 lo esentano.

​

SDKUserMessageReplay

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