Referencia del SDK de Agent - TypeScript

​

Instalación

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

​

Compilar a un ejecutable único

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

• Para compilación cruzada, instale el paquete de plataforma que no coincida, por ejemplo npm install @anthropic-ai/claude-agent-sdk-linux-x64 --force.
• En Windows, la subruta del binario es claude.exe, por ejemplo @anthropic-ai/claude-agent-sdk-win32-x64/claude.exe.

​

Importe la entrada /core cuando agrupe el Agent SDK

​

Funciones

​

query()

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

​

Parámetros

​

Devuelve

​

startup()

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

​

Parámetros

​

Devuelve

​

Ejemplo

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

// Paga el costo de inicio por adelantado
const warm = await startup({ options: { maxTurns: 3 } });

// Más tarde, cuando un prompt esté listo, esto es inmediato
for await (const message of warm.query("What files are here?")) {
  console.log(message);
}

​

prewarm()

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

​

Ejemplo

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

// Al inicio de la aplicación, antes de que se conozca la carpeta de la sesión
const spare = await prewarm({ options: { maxTurns: 3 } });

// Más tarde, cuando el usuario inicia una sesión en una carpeta
const claimedQuery = spare.claim({
  prompt: "What files are here?",
  options: { cwd: "/path/to/project" },
});

spare.claimed.catch((error: Error) => {
  // A menos que el mensaje comience con "option_not_applied", el prompt no se ejecutó:
  // inicia esta sesión con query() en su lugar
  console.error("Claim failed:", error.message);
});

try {
  for await (const message of claimedQuery) {
    console.log(message);
  }
} catch (error) {
  // Tras una reclamación rechazada, la consulta reclamada lanza una excepción una vez que ha emitido el resultado de error
  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>;

​

Parámetros

​

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;

​

Parámetros

​

listSessions()

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

​

Parámetros

​

Tipo de retorno: SDKSessionInfo

​

Ejemplo

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

​

Parámetros

​

Tipo de retorno: SessionMessage

​

Ejemplo

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

​

Parámetros

​

renameSession()

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

​

Parámetros

​

tagSession()

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

​

Parámetros

​

forkSession()

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

​

Parámetros

• sessionId no es un UUID
• no se puede encontrar la sesión, o no tiene mensajes
• upToMessageId no coincide con ningún mensaje de la transcripción

​

resolveSettings()

• policyHelper: resolveSettings() lee fuentes MDM, incluidas plist de macOS y HKLM/HKCU de Windows, pero no ejecuta el subproceso policyHelper configurado por el administrador.
• Configuración administrada por servidor: resolveSettings() no obtiene la configuración administrada por servidor. Pásala como options.serverManagedSettings para incluirla.
• defaultMode: la instantánea devuelve permissions.defaultMode tal como está de todos los niveles, por lo que puede incluir los valores 'auto' y 'bypassPermissions' de la configuración del proyecto y local, que una sesión activa ignora.

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

​

Parámetros

​

Tipo de retorno: ResolvedSettings

​

Ejemplo

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

​

Tipos

​

Options

​

Manejar respuestas de la API lentas o detenidas

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: tiempo de espera por solicitud en el cliente de Anthropic, en milisegundos. Valor predeterminado 600000. Se aplica al bucle principal y a todos los subagentes.
• CLAUDE_CODE_MAX_RETRIES: máximo de reintentos de la API. Predeterminado: 10, con un límite de 15. Cada reintento obtiene su propio intervalo de API_TIMEOUT_MS. Para ejecuciones desatendidas que necesitan esperar durante interrupciones más largas, establece CLAUDE_CODE_RETRY_WATCHDOG=1: reintenta indefinidamente los errores transitorios de capacidad y, en Claude Code v2.1.199 o posterior, eleva a 300 el valor predeterminado para otros errores transitorios y elimina el límite de esta variable.
• CLAUDE_ASYNC_AGENT_STALL_TIMEOUT_MS: watchdog de bloqueos para subagentes. Mientras el watchdog del stream está activado, el valor predeterminado es CLAUDE_STREAM_IDLE_TIMEOUT_MS más 5 minutos, lo que da 600000 a menos que aumentes esa variable. Con el watchdog del stream desactivado, el valor predeterminado es 600000. Antes de v2.1.257, el valor predeterminado siempre era 600000. El temporizador se reinicia con cada evento del stream. Ante un bloqueo, Claude Code aborta el subagente e informa el bloqueo al padre. Para un subagente en segundo plano, también marca la tarea como fallida y adjunta cualquier resultado parcial.
• CLAUDE_ENABLE_STREAM_WATCHDOG con CLAUDE_STREAM_IDLE_TIMEOUT_MS: watchdog del stream que aborta la solicitud cuando los encabezados ya llegaron pero el cuerpo de la respuesta deja de transmitirse. El watchdog está activado de forma predeterminada para todos los proveedores; establece CLAUDE_ENABLE_STREAM_WATCHDOG=0 para desactivarlo. CLAUDE_STREAM_IDLE_TIMEOUT_MS tiene como valor predeterminado 300000 y se limita a ese mínimo. Después de abortar, Reintentos automáticos explica lo que hace Claude Code según cuánto había avanzado la respuesta. Mientras el watchdog espera una respuesta que un gateway detrás de ANTHROPIC_BASE_URL mantiene abierta con pings de keep-alive, un host que establece includePartialMessages sigue recibiendo eventos de stream ping, así que interpreta esos frames como señal de actividad en lugar de agotar el tiempo de espera de la sesión por falta de datos. Antes de v2.1.257, los frames se detenían 5 minutos después del último evento real del stream.

​

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

​

Métodos

​

applyFlagSettings()

• Se aplican en el siguiente turno: effortLevel, ultracode, permissions, hooks, skillOverrides, fastMode, agent. Cambiar agent también aplica la sobrescritura de modelo y los hooks de ese agente en el siguiente turno. Su prompt del sistema se aplica en el siguiente turno o, en una sesión que reutiliza un prompt del sistema registrado, una vez que la sesión se compacta.
• Se aplican durante el turno actual: model. Si cambias model mientras Claude está trabajando en un turno, la respuesta que Claude ya está generando termina con el modelo anterior, y el resto del turno, a partir de la siguiente llamada que Claude Code hace al modelo, usa el nuevo. Los subagentes conservan su propio modelo. Antes de v2.1.212, un cambio a mitad de turno esperaba al siguiente turno.
• Sin efecto durante la sesión: las opciones del prompt del sistema. Se resuelven una sola vez al inicio, por lo que la sesión en ejecución conserva el valor original aunque la llamada tenga éxito. Para cambiarlas, inicia una nueva sesión.

• effortLevel: null devuelve la sesión al nivel de esfuerzo predeterminado del modelo, no a la opción effort de query() ni a un effortLevel de un archivo de configuración.
• agent: null ejecuta el hilo principal sin agente a partir del siguiente turno, en lugar de restaurar la opción agent de query() o un agent de un archivo de configuración. Si el agente borrado había aplicado su propio modelo, la sesión vuelve al modelo que resolvió al inicio.
• ultracode: null desactiva ultracode, igual que false, en lugar de restaurar un valor de ultracode de un archivo de configuración. La sesión conserva su nivel de esfuerzo actual, así que pasa effortLevel en la misma llamada para 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": acepta outputStyle y lo combina en el archivo de configuración local del proyecto, .claude/settings.local.json. El nuevo estilo surte efecto en la siguiente solicitud de la sesión.
• "userSettings": acepta effortLevel y lo guarda como el nivel de esfuerzo predeterminado para el modelo actual de la sesión, bajo modelSettings en tu archivo de configuración de usuario. Pasar max no escribe nada, porque max es solo para la sesión. En cualquier caso, la sesión en ejecución conserva su nivel de esfuerzo actual, así que llama a applyFlagSettings() cuando también quieras cambiarlo. Esta fuente requiere TypeScript SDK v0.3.277 o posterior, que incluye Claude Code v2.1.277.

​

toggleMcpServer()

• Un servidor stdio, SSE o HTTP que agregaste durante la sesión con setMcpServers(): eliminar sus herramientas requiere Claude Code v2.1.285 o posterior.
• Un servidor en proceso que creaste con createSdkMcpServer(), ya sea que lo hayas pasado en mcpServers o con setMcpServers(): desconectarlo y eliminar sus herramientas requiere Claude Code v2.1.286 o posterior. Deshabilitarlo también hace fallar sus llamadas a herramientas que aún están en ejecución, por lo que Claude recibe un resultado de error para cada una de ellas de inmediato, sin esperar a que tu handler retorne.

​

WarmQuery

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

​

Métodos

​

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

​

Miembros

​

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 registró los hooks. El primer initialize de una sesión devuelve este valor. Un initialize repetido enviado por el stdin de la CLI también devuelve true. En ese caso, los hooks de la nueva solicitud reemplazan a los hooks registrados anteriormente.
• false: Claude Code ignoró los hooks. Un initialize repetido enviado a una sesión remota devuelve este valor, de modo que un segundo cliente que se une a una sesión no puede reemplazar los hooks que registró el primer cliente.

• El campo requiere Agent SDK v0.3.296 o posterior, que incluye Claude Code v2.1.296.
• Si el campo es undefined y estableciste pathToClaudeCodeExecutable, apúntalo a Claude Code v2.1.296 o posterior.

​

SDKControlInterruptResponse

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

• Solo aparecen los mensajes que se pusieron en cola con un UUID. Un array vacío no significa que no se vaya a ejecutar nada más.
• Solo se listan los mensajes del hilo principal. Los mensajes dirigidos a un subagente quedan fuera del alcance.
• La lista puede incluir UUID que tu cliente nunca envió, como los disparadores de tareas programadas. Ignora los UUID que no reconozcas en lugar de tratarlos como un error.

​

SDKControlGetContextUsageResponse

• 'full': el valor predeterminado. Claude Code cuenta cada categoría con solicitudes a la API de conteo de tokens. Estas solicitudes no aparecen en el stream de mensajes, por lo que el seguimiento de costos que lee el stream no las verá. En la API de Anthropic, el conteo de tokens no se factura.
• 'summary': pasa { detail: 'summary' } para obtener en su lugar una respuesta basada en el uso de la última respuesta y en estimaciones locales. No se envía ninguna solicitud de conteo de tokens, y los números por categoría son aproximados.

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 los totales por categoría. El kind de cada entrada clasifica la fila con los mismos valores que SDKContextUsageCategory. Clasifica las filas según este campo y no según el name de visualización. El campo requiere Agent SDK v0.3.268 o posterior.
• mcpTools y agents atribuyen tokens a herramientas MCP y subagentes individuales.
• memoryFiles enumera cada archivo de memoria cargado con su costo.
• skills.skillFrontmatter atribuye los tokens del listado de skills a cada skill incluido. Los conteos por skill miden la entrada de cada skill en el listado tal como Claude Code la envía realmente, que puede ser más corta que el frontmatter completo del skill. Compara skills.totalSkills con skills.includedSkills para ver si todos los skills descubiertos llegaron al listado.

​

SDKControlReadFileResponse

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

​

Qué puede leer readFile()

• Un archivo normal dentro de uno de los directorios de trabajo de la sesión, como cwd y additionalDirectories
• Algunos de los propios archivos de Claude Code para la sesión, como los resultados de herramientas

​

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 y mcpServers: los comandos, los subagentes y el estado de los servidores MCP de la sesión, con las mismas formas que devuelven supportedCommands(), supportedAgents() y mcpServerStatus(). supportedAgents() sigue devolviendo la lista capturada en la inicialización, así que lee agents aquí para obtener el conjunto después de una recarga
• plugins: cada plugin cargado con su name y su path de instalación. version repite lo que declara el manifiesto del plugin y lo controla el autor del plugin, así que valídalo antes de confiar en él. Se omite cuando el manifiesto no declara ninguna
• error_count: el número de errores al cargar los plugins

• true: la recarga no se aplicó, y los campos de colección describen la sesión tal como sigue estando. cache_impact indica qué cambiaría al aplicarla. Para aplicarla de todos modos, vuelve a llamar a reloadPlugins() sin la opción.
• false: la comprobación no encontró impacto en la caché, y la recarga se aplicó.
• Ausente: no pasaste la opción, o el ejecutable de Claude Code es anterior a v2.1.268 y aplicó la recarga.

​

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

​

Comportamiento predeterminado

​

Por qué usar 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
  }
});

​

Precedencia de la configuración

1. Configuración local (.claude/settings.local.json)
2. Configuración del proyecto (.claude/settings.json)
3. Configuración del usuario (~/.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" }
];

​

Tipos de Mensajes

​

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': el modelo seleccionado no existe o no está disponible para tu cuenta o despliegue
• 'overloaded': la API devolvió un 529 porque el servidor está a plena capacidad, a diferencia de 'rate_limit', que es un 429 contra tu cuota
• 'account_on_hold': tu cuenta está en espera
• 'cloud_credential_error': Claude Code no pudo obtener credenciales de AWS o Google Cloud utilizables en la máquina en la que se ejecuta, por lo que ninguna solicitud llegó al proveedor de nube. La causa habitual es un inicio de sesión en la nube que expiró o que nunca se completó en esa máquina, aunque un servicio de credenciales brevemente inaccesible reporta el mismo valor. Consulta No se pudieron cargar las credenciales de AWS o Google Cloud. Requiere TypeScript Agent SDK v0.3.267 o posterior, que incluye Claude Code v2.1.267

• La sesión se autentica con una credencial de claude.ai
• La credencial muestra un tipo de plan conocido o tiene el alcance user:profile
• La cuenta no tiene facturación basada en el uso

​

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: si las entradas más los bloques de contenido que contienen suman más de 1,000, Claude Code ignora todo el campo.
• inline_pastes: Claude Code usa las primeras 100 entradas que no están en blanco e ignora el resto.

• shouldQuery: establécelo en false para añadir el mensaje a la transcripción sin activar un turno del asistente. El mensaje se retiene y se fusiona con el siguiente mensaje del usuario que sí activa un turno. Úsalo para inyectar contexto, como la salida de un comando que ejecutaste fuera de banda, sin gastar una llamada al modelo en él.
• client_composed: establécelo en true para que Claude Code entregue el texto del mensaje tal como está escrito. Claude Code entonces no expande las menciones @path ni @server:resource, y no ejecuta como comando el texto que empieza con /. Mientras la opción verbatimPrompts está activada, el SDK establece el campo en cada mensaje. Requiere TypeScript Agent SDK v0.3.280 o posterior y Claude Code v2.1.248 o posterior.
• priority: controla cuándo llega a Claude un mensaje que envías durante un turno en curso:
  • 'next', o sin campo priority: Claude lee el mensaje en el mismo turno, en cuanto terminan las llamadas a herramientas que está ejecutando. Si el turno termina antes, el mensaje inicia el siguiente turno.
  • 'later': Claude Code retiene el mensaje hasta que termina el turno y lo envía como un turno nuevo.
  • 'now' con origin: { kind: "human" }: en Claude Code v2.1.286 o posterior, el trabajo que puede continuar en segundo plano pasa allí, y Claude lee el mensaje en el mismo turno. El trabajo que puede pasar a segundo plano incluye comandos de shell, subagentes y llamadas a herramientas MCP. En v2.1.287 o posterior también incluye las llamadas a WebFetch y WebSearch. Cuando Claude solo está escribiendo una respuesta, o el trabajo que está ejecutando no puede pasar a segundo plano, Claude Code interrumpe el turno en su lugar y Claude lee el mensaje a continuación.
  • 'now' sin ese origen: Claude Code interrumpe el turno y Claude lee el mensaje a continuación.

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

• La herramienta Agent: tool_use_result es AgentOutput. Renderiza a partir de él en lugar de analizar el texto de tool_result. El content de un resultado completed contiene el informe del subagente o, para un subagente cuyo informe pasa por una llamada a la herramienta SubagentHandback, una nota breve sobre esa entrega en lugar del informe. En modo automático en Claude Code v2.1.271 o posterior, todo subagente que produce un resultado completed informa de esa manera a menos que sea un fork, y Claude recibe el informe como un mensaje separado del subagente.
• Una llamada a WebFetch o WebSearch que Claude Code pasó a segundo plano para entregar un mensaje 'now': el mensaje del usuario que lleva el tool_result de esa llamada tiene tool_use_result establecido en { detachedToolCall: true }. La llamada sigue ejecutándose, y Claude recibe su resultado una vez que termina. No llega un segundo tool_result para ese tool_use_id, así que si tu aplicación dibuja una fila por cada llamada a herramienta, marca esta fila como movida a segundo plano cuando llegue este mensaje. Requiere Claude Code v2.1.287 o posterior.
• Una herramienta MCP cuyo resultado contiene bloques resource_link: tool_use_result es un objeto con un arreglo resourceLinks de entradas SDKMcpResourceLink. Claude recibe cada enlace como una línea de texto en el bloque tool_result, así que lee resourceLinks para renderizar los archivos que devolvió el servidor en lugar de analizar ese texto. Claude Code omite resourceLinks cuando el resultado no tiene enlaces y en los resultados de subagentes, conserva como máximo 50 enlaces por resultado y deja de agregar enlaces una vez que el arreglo alcanza 64 KiB de JSON serializado. resourceLinks requiere Agent SDK v0.3.257 o posterior.
• Una herramienta MCP que devuelve structuredContent: tool_use_result es un objeto cuyo miembro structuredContent contiene lo que envió el servidor y cuyo miembro content contiene el valor McpOutput. Los resultados de subagentes no llevan structuredContent.
• Una herramienta MCP cuyo structuredContent se serializa en más de 1,048,576 caracteres de JSON: Claude Code deja structuredContent fuera de tool_use_result y establece structuredContentOmitted: true en su lugar, para que tu aplicación pueda distinguir un objeto descartado de una herramienta que no envió ninguno. Los demás miembros, como content y resourceLinks, se mantienen, y lo que recibe Claude no cambia. Claude Code v2.1.287 o posterior aplica este límite. Dos tipos de herramienta son distintos:
  • Las herramientas de servidores SDK en proceso están exentas y entregan el objeto completo.
  • Una herramienta cuya entrada de tools/list declara un recurso ui:// de MCP Apps tiene un límite de 8,388,608 caracteres en Claude Code v2.1.295 o posterior, y las versiones anteriores a v2.1.295 la eximen.

​

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