> ## Documentation Index
> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Referencia del SDK de Agent - TypeScript

> Referencia completa de la API del SDK de Agent de TypeScript, incluyendo todas las funciones, tipos e interfaces.

<script src="/docs/components/typescript-sdk-type-links.js" defer />

<h2 id="installation">
  Instalación
</h2>

```bash theme={null}
npm install @anthropic-ai/claude-agent-sdk
```

<Note>
  El SDK incluye un binario nativo de Claude Code para su plataforma como una dependencia opcional como `@anthropic-ai/claude-agent-sdk-darwin-arm64`. La mayoría de las instalaciones no necesitan una instalación separada de Claude Code. La versión del SDK rastrea la versión del Claude Code incluida. SDK v0.3.191 incluye Claude Code v2.1.191, por lo que una característica en esta página que requiere una versión de Claude Code necesita la versión del SDK con el mismo número de parche o posterior. Si su gestor de paquetes omite las dependencias opcionales, el SDK lanza `Native CLI binary for <platform>-<arch> not found`; en su lugar, establezca [`pathToClaudeCodeExecutable`](#options) en un binario `claude` instalado por separado.

  Si su gestor de paquetes no aplica el campo `libc` de npm, como Yarn 1.x no lo hace, obtiene tanto los paquetes de plataforma glibc como musl en Linux, aproximadamente duplicando el tamaño de instalación. En Agent SDK v0.2.141 o posterior, el SDK aún lanza la variante correcta. Para recuperar el espacio en una imagen de contenedor, elimine el paquete de plataforma que no coincida con el libc donde se ejecuta su aplicación; para un tiempo de ejecución glibc en x64, eso es `rm -rf node_modules/@anthropic-ai/claude-agent-sdk-linux-x64-musl`. En una máquina de desarrollo la eliminación es temporal, ya que Yarn reinstala el paquete en el siguiente cambio de dependencia.
</Note>

<h3 id="compile-to-a-single-executable">
  Compilar a un ejecutable único
</h3>

Cuando compila su aplicación en un ejecutable de un solo archivo con `bun build --compile`, el SDK no puede resolver el binario CLI incluido en tiempo de ejecución. `require.resolve` no funciona dentro del sistema de archivos virtual `$bunfs` del ejecutable compilado, por lo que el SDK lanza `Native CLI binary for <platform>-<arch> not found`.

Para solucionar esto, incruste el binario de plataforma como un activo de archivo, extráigalo a una ruta real al inicio con `extractFromBunfs()`, y pase esa ruta a [`pathToClaudeCodeExecutable`](#options).

El asistente `extractFromBunfs()` requiere `@anthropic-ai/claude-agent-sdk` v0.3.144 o posterior. El ejemplo a continuación se compila para macOS en Apple Silicon:

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

const cliPath = extractFromBunfs(binPath);

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

`extractFromBunfs()` copia el binario incrustado fuera del sistema de archivos virtual del ejecutable compilado a un directorio temporal por usuario y devuelve la ruta real. Fuera de un ejecutable compilado, devuelve la ruta de entrada sin cambios, por lo que el mismo código se ejecuta en desarrollo sin modificación.

Cada ejecutable compilado incrusta el binario de una única plataforma. Haga coincidir el paquete de plataforma en la importación con su `--target`:

* 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`.

<h3 id="import-the-/core-entry-when-you-bundle-the-agent-sdk">
  Importe la entrada `/core` cuando agrupe el Agent SDK
</h3>

Si su aplicación agrupa el Agent SDK junto con sus propias dependencias, importe desde `@anthropic-ai/claude-agent-sdk/core` en lugar de la raíz del paquete. La entrada `/core` requiere Agent SDK de TypeScript v0.3.282 o posterior, y sus tipos requieren TypeScript 5.0 o posterior.

La entrada `/core` exporta el mismo `query()`, `startup()`, `tool()`, `createSdkMcpServer()`, y `resolveSettings()` que la entrada raíz, junto con las funciones que renombran, etiquetan y eliminan sesiones, `AbortError`, las constantes de tiempo de ejecución, y cada tipo. No añade nombres propios. Para mantener pequeño el código que carga su aplicación, `/core` omite algunas exportaciones raíz, incluyendo `prewarm()`, la clase `InMemorySessionStore`, y los asistentes que listan, leen, bifurcan, importan y resumen sesiones. Si necesita uno de ellos, use la entrada raíz en su lugar.

La entrada raíz inserta sus propias copias de `zod` y `@modelcontextprotocol/sdk`. La entrada `/core` las importa desde su `node_modules` en los rangos que las `peerDependencies` del Agent SDK declaran, por lo que un paquete que ya las incluye no lleva una segunda copia. Importe desde la raíz o `/core` en un proceso dado, no ambas: son paquetes separados, y cargar ambas le da dos copias de las clases y el estado del Agent SDK.

<h2 id="functions">
  Funciones
</h2>

<h3 id="query">
  `query()`
</h3>

La función principal para interactuar con Claude Code. Crea un generador asincrónico que transmite mensajes a medida que llegan.

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

<h4 id="parameters">
  Parámetros
</h4>

| Parámetro | Tipo | Descripción |
| :- | :- | :- |
| `prompt` | `string \| AsyncIterable<`[`SDKUserMessage`](#sdkusermessage)`>` | El mensaje de entrada como una cadena o iterable asincrónico para el modo de transmisión |
| `options` | [`Options`](#options) | Objeto de configuración opcional (vea el tipo Options a continuación) |

<h4 id="returns">
  Devuelve
</h4>

Devuelve un objeto [`Query`](#query-object) que extiende `AsyncGenerator<`[`SDKMessage`](#sdkmessage)`, void>` con métodos adicionales.

<h3 id="startup">
  `startup()`
</h3>

Precalienta el subproceso CLI iniciándolo y completando el protocolo de inicialización antes de que un mensaje esté disponible. El identificador [`WarmQuery`](#warmquery) devuelto acepta un mensaje más tarde y lo escribe en un proceso ya listo, por lo que la primera llamada a `query()` se resuelve sin pagar el costo de generación e inicialización del subproceso en línea. Si aún no conoce el directorio de trabajo de la sesión, use [`prewarm()`](#prewarm) en su lugar.

```typescript theme={null}
function startup(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<WarmQuery>;
```

<h4 id="parameters-2">
  Parámetros
</h4>

| Parámetro | Tipo | Descripción |
| :- | :- | :- |
| `options` | [`Options`](#options) | Objeto de configuración opcional. Igual que el parámetro `options` para `query()` |
| `initializeTimeoutMs` | `number` | Tiempo máximo en milisegundos para esperar la inicialización del subproceso. Por defecto es `60000`. Si la inicialización no se completa a tiempo, la promesa se rechaza con un error de tiempo de espera |

<h4 id="returns-2">
  Devuelve
</h4>

Devuelve una `Promise<`[`WarmQuery`](#warmquery)`>` que se resuelve una vez que el subproceso se ha generado y ha completado su protocolo de inicialización.

<h4 id="example">
  Ejemplo
</h4>

Llame a `startup()` temprano, por ejemplo al inicio de la aplicación, luego llame a `.query()` en el identificador devuelto una vez que un mensaje esté listo. Esto mueve la generación del subproceso e inicialización fuera de la ruta crítica.

```typescript theme={null}
import { startup } from "@anthropic-ai/claude-agent-sdk";

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

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

<h3 id="prewarm">
  `prewarm()`
</h3>

*Alfa.* Inicia un proceso de Claude Code como repuesto antes de saber qué sesión servirá, para que pueda vincularlo a una sesión más tarde con [`claim()`](#spareprocess). Úselo en una aplicación que se inicia antes de que el usuario elija una carpeta. Requiere TypeScript Agent SDK v0.3.282 o posterior.

`prewarm()` completa el mismo protocolo de inicialización que [`startup()`](#startup), con el proceso esperando en `options.cwd` cuando lo establece y de lo contrario en un directorio temporal privado bajo su directorio de configuración de Claude Code. El directorio de trabajo de la sesión, sus hooks `SessionStart`, sus servidores MCP de stdio, y su contexto CLAUDE.md y git esperan la reclamación. Un repuesto ocupa aproximadamente 230 a 260 MB de memoria mientras espera. Si su [`spawnClaudeCodeProcess`](#options) ejecuta Claude Code en otra máquina o en un contenedor, establezca `options.cwd` en un directorio que exista allí para que el repuesto espere.

```typescript theme={null}
function prewarm(params?: {
  options?: Options;
  initializeTimeoutMs?: number;
}): Promise<SpareProcess>;
```

`options` e `initializeTimeoutMs` significan lo mismo que para `startup()`, excepto que `options.cwd` establece solo el directorio en el que el repuesto espera. La promesa se resuelve con un [`SpareProcess`](#spareprocess) una vez que el proceso ha completado su protocolo de inicialización. `prewarm()` lanza una excepción si `options` establece `resume`, `continue`, o `forkSession`, porque un repuesto aún no tiene sesión. Todo lo que una reclamación no puede establecer, como `mcpServers`, `hooks`, `canUseTool`, `settingSources`, `systemPrompt`, y `plugins`, se fija para la vida útil del repuesto, por lo que mantenga un repuesto por conjunto distinto de esas opciones y precaliente nuevamente cuando cambien.

<h4 id="example-2">
  Ejemplo
</h4>

Precaliente al inicio de la aplicación, luego reclame el repuesto cuando el usuario inicie una sesión:

```typescript theme={null}
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 mensaje no se ejecutó:
  // inicie esta sesión con query() en su lugar
  console.error("Claim failed:", error.message);
});

for await (const message of claimedQuery) {
  console.log(message);
}
```

<h3 id="tool">
  `tool()`
</h3>

Crea una definición de herramienta MCP segura de tipos para usar con servidores MCP del SDK.

```typescript theme={null}
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>;
```

<h4 id="parameters-3">
  Parámetros
</h4>

| Parámetro | Tipo | Descripción |
| :- | :- | :- |
| `name` | `string` | El nombre de la herramienta |
| `description` | `string` | Una descripción de lo que hace la herramienta |
| `inputSchema` | `Schema extends AnyZodRawShape` | Esquema Zod que define los parámetros de entrada de la herramienta (soporta tanto Zod 3 como Zod 4) |
| `handler` | `(args, extra) => Promise<`[`CallToolResult`](#calltoolresult)`>` | Función asincrónica que ejecuta la lógica de la herramienta |
| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)`; searchHint?: string; alwaysLoad?: boolean }` | Extras opcionales. `annotations` proporciona sugerencias de comportamiento MCP a los clientes. `searchHint` es una frase de capacidad de una línea que se muestra en la lista de herramientas diferidas cuando la [búsqueda de herramientas](/docs/es/agent-sdk/tool-search) está activa. `alwaysLoad: true` mantiene el esquema completo de esta herramienta en el mensaje inicial en lugar de diferirlo |

<h4 id="toolannotations">
  `ToolAnnotations`
</h4>

Definido en `@modelcontextprotocol/sdk/types.js`. Todos los campos son sugerencias opcionales; los clientes no deben confiar en ellos para decisiones de seguridad.

| Campo | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `title` | `string` | `undefined` | Título legible por humanos para la herramienta |
| `readOnlyHint` | `boolean` | `false` | Si es `true`, la herramienta no modifica su entorno |
| `destructiveHint` | `boolean` | `true` | Si es `true`, la herramienta puede realizar actualizaciones destructivas (solo significativo cuando `readOnlyHint` es `false`) |
| `idempotentHint` | `boolean` | `false` | Si es `true`, las llamadas repetidas con los mismos argumentos no tienen efecto adicional (solo significativo cuando `readOnlyHint` es `false`) |
| `openWorldHint` | `boolean` | `true` | Si es `true`, la herramienta interactúa con entidades externas (por ejemplo, búsqueda web). Si es `false`, el dominio de la herramienta es cerrado (por ejemplo, una herramienta de memoria) |

```typescript theme={null}
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 } }
);
```

<h3 id="createsdkmcpserver">
  `createSdkMcpServer()`
</h3>

Crea una instancia de servidor MCP que se ejecuta en el mismo proceso que su aplicación.

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

<h4 id="parameters-4">
  Parámetros
</h4>

| Parámetro | Tipo | Descripción |
| :- | :- | :- |
| `options.name` | `string` | El nombre del servidor MCP |
| `options.version` | `string` | Cadena de versión opcional |
| `options.instructions` | `string` | Instrucciones del servidor opcionales, devueltas desde `initialize` y expuestas al modelo como un bloque de instrucciones MCP |
| `options.tools` | `Array<SdkMcpToolDefinition>` | Matriz de definiciones de herramientas creadas con [`tool()`](#tool) |
| `options.alwaysLoad` | `boolean` | Cuando es `true`, cada herramienta de este servidor permanece en el prompt inicial en lugar de diferirse detrás de la [búsqueda de herramientas](/docs/es/agent-sdk/tool-search). Se combina con `alwaysLoad` por herramienta en [`tool()`](#tool) |
| `options.timeout` | `number` | Tiempo de espera en milisegundos para las llamadas de herramientas de este servidor. Claude Code lo aplica a este servidor en lugar de [`MCP_TOOL_TIMEOUT`](/docs/es/env-vars). Pase un número entero de al menos 1000. Claude Code ignora otros valores. Requiere TypeScript Agent SDK v0.3.248 o posterior |

<h3 id="listsessions">
  `listSessions()`
</h3>

Descubre y enumera sesiones pasadas con metadatos ligeros. Filtre por directorio de proyecto o enumere sesiones en todos los proyectos.

```typescript theme={null}
function listSessions(options?: ListSessionsOptions): Promise<SDKSessionInfo[]>;
```

<h4 id="parameters-5">
  Parámetros
</h4>

| Parámetro | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `options.dir` | `string` | `undefined` | Directorio para enumerar sesiones. Cuando se omite, devuelve sesiones en todos los proyectos |
| `options.limit` | `number` | `undefined` | Número máximo de sesiones a devolver |
| `options.includeWorktrees` | `boolean` | `true` | Cuando `dir` está dentro de un repositorio git, incluya sesiones de todas las rutas de worktree |

<h4 id="return-type-sdksessioninfo">
  Tipo de retorno: `SDKSessionInfo`
</h4>

| Propiedad | Tipo | Descripción |
| :- | :- | :- |
| `sessionId` | `string` | Identificador de sesión único (UUID) |
| `summary` | `string` | Título de visualización: título personalizado, resumen generado automáticamente o primer mensaje |
| `lastModified` | `number` | Última hora de modificación en milisegundos desde la época |
| `fileSize` | `number \| undefined` | Tamaño del archivo de sesión en bytes. Solo se completa para almacenamiento JSONL local |
| `customTitle` | `string \| undefined` | Título de sesión establecido por el usuario cuando se establece uno, por ejemplo con `--name`, `/rename`, la salida `sessionTitle` de un hook, o [`renameSession()`](#renamesession). De lo contrario, el título de sesión generado por IA, si la sesión tiene uno |
| `firstPrompt` | `string \| undefined` | Primer mensaje de usuario significativo en la sesión |
| `gitBranch` | `string \| undefined` | Rama Git al final de la sesión |
| `cwd` | `string \| undefined` | Directorio de trabajo para la sesión |
| `tag` | `string \| undefined` | Etiqueta de sesión establecida por el usuario (vea [`tagSession()`](#tagsession)) |
| `createdAt` | `number \| undefined` | Hora de creación en milisegundos desde la época, de la marca de tiempo de la primera entrada |

<h4 id="example-3">
  Ejemplo
</h4>

Imprima las 10 sesiones más recientes para un proyecto. Los resultados se ordenan por `lastModified` descendente, por lo que el primer elemento es el más nuevo. Omita `dir` para buscar en todos los proyectos.

```typescript theme={null}
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})`);
}
```

<h3 id="getsessionmessages">
  `getSessionMessages()`
</h3>

Lee mensajes de usuario y asistente de una transcripción de sesión pasada.

```typescript theme={null}
function getSessionMessages(
  sessionId: string,
  options?: GetSessionMessagesOptions
): Promise<SessionMessage[]>;
```

<h4 id="parameters-6">
  Parámetros
</h4>

| Parámetro | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `sessionId` | `string` | requerido | UUID de sesión a leer (vea `listSessions()`) |
| `options.dir` | `string` | `undefined` | Directorio de proyecto para encontrar la sesión. Cuando se omite, busca en todos los proyectos |
| `options.limit` | `number` | `undefined` | Número máximo de mensajes a devolver |
| `options.offset` | `number` | `undefined` | Número de mensajes a omitir desde el inicio |

<h4 id="return-type-sessionmessage">
  Tipo de retorno: `SessionMessage`
</h4>

| Propiedad | Tipo | Descripción |
| :- | :- | :- |
| `type` | `"user" \| "assistant"` | Rol del mensaje |
| `uuid` | `string` | Identificador de mensaje único |
| `session_id` | `string` | Sesión a la que pertenece este mensaje |
| `message` | `unknown` | Carga útil de mensaje sin procesar de la transcripción |
| `parent_tool_use_id` | `string \| null` | Para mensajes de subagente, el `tool_use_id` de la llamada de herramienta `Agent` o `Skill` que inició el subagente. `null` para mensajes de sesión principal y sesiones más antiguas |
| `parent_agent_id` | `string \| null` | Para mensajes de un [subagente anidado](/docs/es/sub-agents#let-subagents-spawn-their-own-subagents), el `agentId` del subagente que lo generó. `null` para mensajes de sesión principal, mensajes de subagentes de nivel superior y sesiones más antiguas. Requiere Claude Code v2.1.202 o posterior |

<h4 id="example-4">
  Ejemplo
</h4>

```typescript theme={null}
import { listSessions, getSessionMessages } from "@anthropic-ai/claude-agent-sdk";

const [latest] = await listSessions({ dir: "/path/to/project", limit: 1 });

if (latest) {
  const messages = await getSessionMessages(latest.sessionId, {
    dir: "/path/to/project",
    limit: 20
  });

  for (const msg of messages) {
    console.log(`[${msg.type}] ${msg.uuid}`);
  }
}
```

<h3 id="getsessioninfo">
  `getSessionInfo()`
</h3>

Lee metadatos para una única sesión por ID sin escanear el directorio de proyecto completo.

```typescript theme={null}
function getSessionInfo(
  sessionId: string,
  options?: GetSessionInfoOptions
): Promise<SDKSessionInfo | undefined>;
```

<h4 id="parameters-7">
  Parámetros
</h4>

| Parámetro | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `sessionId` | `string` | requerido | UUID de la sesión a buscar |
| `options.dir` | `string` | `undefined` | Ruta del directorio del proyecto. Cuando se omite, busca en todos los directorios de proyecto |

Devuelve [`SDKSessionInfo`](#return-type-sdksessioninfo), o `undefined` si la sesión no se encuentra.

<h3 id="renamesession">
  `renameSession()`
</h3>

Cambia el nombre de una sesión añadiendo una entrada de título personalizado. Las llamadas repetidas son seguras; el título más reciente gana.

```typescript theme={null}
function renameSession(
  sessionId: string,
  title: string,
  options?: SessionMutationOptions
): Promise<void>;
```

<h4 id="parameters-8">
  Parámetros
</h4>

| Parámetro | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `sessionId` | `string` | requerido | UUID de la sesión a renombrar |
| `title` | `string` | requerido | Nuevo título. Debe ser no vacío después de recortar espacios en blanco |
| `options.dir` | `string` | `undefined` | Ruta del directorio del proyecto. Cuando se omite, busca en todos los directorios de proyecto |

<h3 id="tagsession">
  `tagSession()`
</h3>

Etiqueta una sesión. Pase `null` para borrar la etiqueta. Las llamadas repetidas son seguras; la etiqueta más reciente gana.

```typescript theme={null}
function tagSession(
  sessionId: string,
  tag: string | null,
  options?: SessionMutationOptions
): Promise<void>;
```

<h4 id="parameters-9">
  Parámetros
</h4>

| Parámetro | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `sessionId` | `string` | requerido | UUID de la sesión a etiquetar |
| `tag` | `string \| null` | requerido | Cadena de etiqueta, o `null` para borrar |
| `options.dir` | `string` | `undefined` | Ruta del directorio del proyecto. Cuando se omite, busca en todos los directorios de proyecto |

<h3 id="resolvesettings">
  `resolveSettings()`
</h3>

Resuelve la configuración efectiva de Claude Code para un directorio determinado utilizando el mismo motor de fusión que la CLI, sin generar la CLI de Claude. Úselo para inspeccionar qué configuración vería una llamada a `query()` antes de invocar una.

<Note>
  Esta función es alfa y su API puede cambiar antes de la estabilización.
</Note>

La instantánea difiere de lo que una sesión `query()` activa aplica:

* **`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 [configuración administrada por servidor](/docs/es/server-managed-settings#fetch-and-caching-behavior). Páselas como `options.serverManagedSettings` para incluirlas.
* **`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](/docs/es/permission-modes#which-mode-a-session-starts-in).

```typescript theme={null}
function resolveSettings(
  options?: ResolveSettingsOptions
): Promise<ResolvedSettings>;
```

<h4 id="parameters-10">
  Parámetros
</h4>

`resolveSettings()` acepta un único objeto de opciones. Todos los campos son opcionales.

| Parámetro | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `options.cwd` | `string` | `process.cwd()` | Directorio para resolver la configuración del proyecto y local relativa a |
| `options.settingSources` | [`SettingSource`](#settingsource)`[]` | Todas las fuentes | Qué fuentes del sistema de archivos cargar. Pase `[]` para omitir la configuración del usuario, proyecto y local. La [política administrada por punto final](/docs/es/managed-settings#delivery-mechanisms) se carga en todos los casos. `resolveSettings()` incluye configuración administrada por servidor solo cuando pasa `options.serverManagedSettings` |
| `options.managedSettings` | `Settings` | `undefined` | Configuración de nivel de política suministrada por el host de incrustación. Sigue las mismas reglas que [`managedSettings` en `Options`](#options), excepto que `resolveSettings()` no ejecuta un [`policyHelper`](/docs/es/settings-reference#policyhelper) configurado, por lo que la instantánea puede incluir configuración que una sesión activa descarta |
| `options.serverManagedSettings` | `Settings` | `undefined` | Carga útil de configuración administrada por servidor desde `/api/claude_code/settings`. Las claves no restrictivas pasan sin filtrar |

<h4 id="return-type-resolvedsettings">
  Tipo de retorno: `ResolvedSettings`
</h4>

`resolveSettings()` devuelve un objeto que describe la configuración fusionada y la fuente que contribuyó a cada clave.

| Propiedad | Tipo | Descripción |
| :- | :- | :- |
| `effective` | `Settings` | Configuración fusionada después de aplicar todas las fuentes habilitadas en orden de precedencia |
| `provenance` | `Partial<Record<keyof Settings, ProvenanceEntry>>` | Para cada clave de nivel superior en `effective`, qué fuente suministró el valor |
| `sources` | `Array<{ source, settings, path?, policyOrigin? }>` | Configuración sin procesar por fuente, ordenada de precedencia más baja a más alta |

<h4 id="example-5">
  Ejemplo
</h4>

El ejemplo a continuación resuelve la configuración para un directorio de proyecto e imprime la fuente que controla el período de limpieza. En una máquina donde ningún archivo de configuración establece `cleanupPeriodDays`, ambas líneas impresas muestran `undefined` para el valor, que es la salida esperada en lugar de un error.

```typescript theme={null}
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}`);
```

<h2 id="types">
  Tipos
</h2>

<h3 id="options">
  `Options`
</h3>

Objeto de configuración para la función `query()`.

| Propiedad | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `abortController` | `AbortController` | `new AbortController()` | Controlador para cancelar operaciones |
| `additionalDirectories` | `string[]` | `[]` | Directorios adicionales a los que Claude puede acceder. El SDK pasa cada entrada a Claude Code como `--add-dir`, por lo que con la fuente de configuración `project` Claude Code también [carga los skills, comandos y subagentes del directorio](/docs/es/permissions#additional-directories-grant-file-access-not-configuration) |
| `agent` | `string` | `undefined` | Nombre del agente para el hilo principal. El agente debe estar definido en la opción `agents` o en la configuración |
| `agents` | `Record<string, [`AgentDefinition`](#agentdefinition)>` | `undefined` | Define subagentes mediante programación |
| `agentProgressSummaries` | `boolean` | `false` | Cuando es `true`, genera resúmenes de progreso de una línea para los subagentes y los reenvía en los eventos [`task_progress`](#sdktaskprogressmessage) mediante el campo `summary`. Se aplica a subagentes en primer plano y en segundo plano |
| `allowDangerouslySkipPermissions` | `boolean` | `false` | Habilita la omisión de permisos. Es obligatorio al usar `permissionMode: 'bypassPermissions'`, ya sea al inicio o más tarde mediante `setPermissionMode()`. Consulta [modo plan](/docs/es/agent-sdk/permissions#plan-mode-plan) para ver cómo interactúa con `permissionMode: 'plan'` |
| `allowedTools` | `string[]` | `[]` | Herramientas que se aprueban automáticamente sin pedir confirmación. Esto no restringe a Claude a usar solo estas herramientas. Si nombras aquí una de las [herramientas de seguimiento de tareas](/docs/es/agent-sdk/todo-tracking#model-availability), Claude Code también habilita su uso en la sesión. Las demás herramientas no listadas pasan a `permissionMode` y `canUseTool`. Usa `disallowedTools` para bloquear herramientas. Consulta [Permisos](/docs/es/agent-sdk/permissions#allow-and-deny-rules) |
| `betas` | [`SdkBeta`](#sdkbeta)`[]` | `[]` | Habilita funciones beta |
| `canUseTool` | [`CanUseTool`](#canusetool) | `undefined` | Función de permisos personalizada, que se invoca solo cuando el [flujo de permisos](/docs/es/agent-sdk/permissions#how-permissions-are-evaluated) llega a una solicitud de permiso. No se invoca para las llamadas aprobadas automáticamente por `allowedTools`, por reglas de permiso o por `permissionMode`. Una regla de permiso no aprueba previamente las [acciones que ningún modo aprueba automáticamente](/docs/es/permission-modes#actions-no-mode-auto-approves). Consulta [`CanUseTool`](#canusetool) para más detalles |
| `continue` | `boolean` | `false` | Continúa la conversación más reciente |
| `cwd` | `string` | `process.cwd()` | Directorio de trabajo actual |
| `debug` | `boolean` | `false` | Habilita el modo de depuración para el proceso de Claude Code |
| `debugFile` | `string` | `undefined` | Escribe los registros de depuración en una ruta de archivo específica. Habilita implícitamente el modo de depuración |
| `disallowedTools` | `string[]` | `[]` | Herramientas que se deniegan. Un nombre sin más, como `"Bash"`, elimina la herramienta del contexto de Claude. Una regla con alcance, como `"Bash(rm *)"`, deja la herramienta disponible y deniega las llamadas coincidentes en todos los modos de permisos, incluido `bypassPermissions`, para el comando [tal como está escrito](/docs/es/permissions#bash-rule-limits). Consulta [Permisos](/docs/es/agent-sdk/permissions#allow-and-deny-rules) |
| `effort` | `'low' \| 'medium' \| 'high' \| 'xhigh' \| 'max'` | `undefined` | Controla cuánto esfuerzo pone Claude en su respuesta. Funciona con el pensamiento adaptativo para orientar la profundidad del pensamiento. Consulta [ajustar el nivel de esfuerzo](/docs/es/model-config#adjust-effort-level) |
| `enableFileCheckpointing` | `boolean` | `false` | Habilita el seguimiento de cambios en archivos para poder rebobinar. Consulta [Checkpointing de archivos](/docs/es/agent-sdk/file-checkpointing) |
| `env` | `Record<string, string \| undefined>` | `process.env` | Variables de entorno. Cuando se establece, reemplaza el entorno del subproceso en lugar de combinarse con `process.env`, así que pasa `{ ...process.env, YOUR_VAR: 'value' }` para conservar variables heredadas como `PATH`. Consulta [Manejar respuestas de API lentas o detenidas](#handle-slow-or-stalled-api-responses) para ver un ejemplo de este patrón, y [Variables de entorno](/docs/es/env-vars) para ver las variables que lee la CLI subyacente. Establece `CLAUDE_AGENT_SDK_CLIENT_APP` para identificar tu app en el encabezado User-Agent |
| `executable` | `'bun' \| 'deno' \| 'node'` | Detectado automáticamente | Runtime de JavaScript que se usará |
| `executableArgs` | `string[]` | `[]` | Argumentos que se pasan al ejecutable |
| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionales |
| `fallbackModel` | `string` | `undefined` | Modelo que se usará si el modelo principal falla. Acepta una lista separada por comas. Para el orden y el límite, consulta [Cadenas de modelos de respaldo](/docs/es/model-config#fallback-model-chains). Para orientación, consulta [Elegir un modelo](/docs/es/agent-sdk/configuration#choose-a-model) |
| `forkSession` | `boolean` | `false` | Al reanudar con `resume`, bifurca a un nuevo ID de sesión en lugar de continuar la sesión original |
| `forwardSubagentText` | `boolean` | `false` | Reenvía el texto y los bloques de pensamiento de los subagentes como mensajes de asistente y de usuario con `parent_tool_use_id` establecido, para que los consumidores puedan renderizar una transcripción anidada. Sin esta opción, Claude Code emite los bloques `tool_use` y `tool_result` de los subagentes, pero no el texto ni el pensamiento. Los mensajes de subagentes en cualquier nivel de anidamiento se reenvían en Claude Code v2.1.219 y posteriores; antes de v2.1.219, solo aparecían los mensajes de subagentes de profundidad 1. Los mensajes de los subagentes que genera un skill bifurcado, y los de skills bifurcados anidados, requieren v2.1.275 o posterior |
| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Callbacks de hooks para eventos |
| `includeHookEvents` | `boolean` | `false` | Incluye los eventos del ciclo de vida de los hooks en el flujo de mensajes como [`SDKHookStartedMessage`](#sdkhookstartedmessage), [`SDKHookProgressMessage`](#sdkhookprogressmessage) y [`SDKHookResponseMessage`](#sdkhookresponsemessage). Los eventos del ciclo de vida de los hooks `SessionStart` y `Setup` siempre se incluyen y no necesitan esta opción. Algunos eventos de hooks, como `Notification`, `SessionEnd`, `PreCompact` y `PostCompact`, nunca producen un `SDKHookStartedMessage`, incluso con esta opción. Para esos eventos, Claude Code igualmente emite un `SDKHookProgressMessage` mientras un hook de comando que se ejecuta durante más de un segundo produce salida, y emite un `SDKHookResponseMessage` solo cuando termina un hook [que se ejecuta en segundo plano](/docs/es/hooks#run-hooks-in-the-background) |
| `includePartialMessages` | `boolean` | `false` | Incluye eventos de mensajes parciales |
| `loadTimeoutMs` | `number` | `60000` | *Alpha.* Tiempo de espera en milisegundos para cada llamada a `sessionStore.load()` y `sessionStore.listSubkeys()` durante la materialización de la reanudación. Si el adaptador no se resuelve dentro de este plazo, la consulta falla en lugar de quedarse colgada. Se ignora cuando `sessionStore` no está establecido |
| `managedSettings` | `Settings` | `undefined` | Configuración de nivel de política que tu proceso host proporciona a la sesión generada. En máquinas con configuración administrada desplegada por un administrador, Claude Code la ignora a menos que la fuente administrada de mayor prioridad del administrador establezca `parentSettingsBehavior: 'merge'`, y nunca la combina mientras un [`policyHelper`](/docs/es/settings-reference#policyhelper) proporcione configuración administrada. Los valores combinados pasan por un filtro que solo admite restricciones; [Restringir la configuración principal](/docs/es/claude-apps-gateway#restrict-parent-settings) explica qué admite el filtro y los bloqueos `allowManaged*Only`. En un host que establece [`CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST`](/docs/es/env-vars), en cambio, se leen tres claves directamente de este payload: su [configuración de modelos](/docs/es/model-config#restrict-model-selection) en Claude Code v2.1.222 o posterior, [`modelPricing`](/docs/es/settings-reference#modelpricing) cuando ninguna fuente administrada lo establece en v2.1.246 o posterior, y su entrada env `ENABLE_TOOL_SEARCH` en v2.1.247 o posterior |
| `maxBudgetUsd` | `number` | `undefined` | Detiene la consulta cuando la estimación de costo del lado del cliente alcanza este valor en USD. Solo cuenta el gasto propio de la llamada; los totales restaurados de una sesión reanudada no cuentan. Para advertencias sobre la precisión y el comportamiento de restablecimiento, consulta [Seguimiento de costos y uso](/docs/es/agent-sdk/cost-tracking) |
| `maxThinkingTokens` | `number` | `undefined` | *Obsoleto:* usa `thinking` en su lugar. Máximo de tokens para el proceso de pensamiento |
| `maxTurns` | `number` | `undefined` | Máximo de turnos agénticos (idas y vueltas de uso de herramientas) |
| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configuraciones de servidores MCP |
| `model` | `string` | Predeterminado de la CLI | Alias del modelo de Claude o nombre completo del modelo. Consulta [valores aceptados e IDs específicos de cada proveedor](/docs/es/model-config#available-models) |
| `onElicitation` | `(request: ElicitationRequest, options: { signal: AbortSignal }) => Promise<ElicitationResult>` | `undefined` | Callback para manejar solicitudes de elicitación de MCP. Se llama cuando un servidor MCP solicita información al usuario y ningún hook la maneja primero. Si no se proporciona, las solicitudes de elicitación no manejadas se rechazan automáticamente |
| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Define el formato de salida para los resultados del agente. Consulta [Salidas estructuradas](/docs/es/agent-sdk/structured-outputs) para más detalles |
| `outputStyle` | `string` | `undefined` | No es un campo de `Options`. Establece `outputStyle` en el objeto [`settings`](/docs/es/settings) en línea o en un archivo de configuración. Consulta [Activar un estilo de salida](/docs/es/agent-sdk/modifying-system-prompts#activate-an-output-style) |
| `pathToClaudeCodeExecutable` | `string` | Se resuelve automáticamente desde el binario nativo incluido | Ruta al ejecutable de Claude Code. Solo es necesaria si se omitieron las dependencias opcionales durante la instalación o si tu plataforma no está en el conjunto compatible |
| `permissionMode` | [`PermissionMode`](#permissionmode) | `undefined` | Modo de permisos para la sesión. Si lo omites, la sesión puede iniciarse en modo automático. Consulta [Modos de permisos](/docs/es/agent-sdk/permissions#permission-modes) para ver cómo elige Claude Code el modo de permisos inicial |
| `permissionPromptToolName` | `string` | `undefined` | Nombre de la herramienta MCP para las solicitudes de permiso |
| `permissionPrompts` | `'host' \| 'none'` | `'host'` | Quién responde las solicitudes de permiso: `'host'` las dirige a tu callback [`canUseTool`](#canusetool) o a la herramienta `permissionPromptToolName`, y `'none'` [deniega las llamadas que habrían requerido una solicitud](/docs/es/agent-sdk/permissions#how-permissions-are-evaluated). Requiere Claude Code v2.1.259 o posterior |
| `persistSession` | `boolean` | `true` | Cuando es `false`, deshabilita la persistencia de la sesión en disco. Las sesiones no se pueden reanudar después |
| `planModeInstructions` | `string` | `undefined` | Instrucciones de flujo de trabajo personalizadas para el modo plan. Cuando `permissionMode` es `'plan'`, esta cadena reemplaza el cuerpo predeterminado del flujo de trabajo del modo plan. La CLI igualmente la envuelve con el preámbulo que impone el modo de solo lectura y el pie del protocolo ExitPlanMode |
| `plugins` | [`SdkPluginConfig`](#sdkpluginconfig)`[]` | `[]` | Carga plugins personalizados desde rutas locales. Consulta [Plugins](/docs/es/agent-sdk/plugins) para más detalles |
| `projectConfigRoot` | `string` | `undefined` | Ruta absoluta del checkout de confianza del que `cwd` es un worktree. Claude Code lee la configuración del proyecto, `.mcp.json` y los comandos, agentes, skills, flujos de trabajo, rutinas y estilos de salida de `.claude/` del proyecto desde este directorio en lugar de `cwd`, y establece `CLAUDE_PROJECT_DIR` en él. Los hooks, los scripts auxiliares como `apiKeyHelper` y los servidores MCP stdio se inician con este directorio como directorio de trabajo. Los archivos `CLAUDE.md` y `.claude/rules/` se siguen cargando desde `cwd`. Requiere Claude Code v2.1.275 o posterior |
| `promptSuggestions` | `boolean` | `false` | Habilita las sugerencias de prompts. Después de un turno, Claude Code emite un mensaje `prompt_suggestion` que contiene una predicción del siguiente prompt del usuario. Claude Code no genera sugerencias en algunos turnos, por ejemplo cuando tu cuenta está cerca de su límite de uso o ya lo alcanzó. Consulta [Cuándo Claude Code omite las sugerencias](/docs/es/interactive-mode#when-claude-code-skips-suggestions) |
| `resume` | `string` | `undefined` | ID de la sesión que se reanudará |
| `resumeDropsTurn` | `string` | `undefined` | Con `resumeSessionAt`: el UUID del prompt del turno que la reanudación con truncamiento pretende descartar. Claude Code rechaza la reanudación cuando el rango descartado contiene algo que no se puede atribuir a ese turno, como mensajes en cola absorbidos o notificaciones de tareas, y nombra el flag `--resume-drops-turn` en el mensaje de rechazo. Solo las reanudaciones del Agent SDK y del modo print leen este par. Requiere Claude Code v2.1.223 o posterior |
| `resumeSessionAt` | `string` | `undefined` | Reanuda la sesión en un UUID de mensaje específico |
| `sandbox` | [`SandboxSettings`](#sandboxsettings) | `undefined` | Configura el comportamiento del sandbox mediante programación. Consulta [Configuración del sandbox](#sandboxsettings) para más detalles |
| `sessionId` | `string` | Generado automáticamente | Usa un UUID específico para la sesión en lugar de generar uno automáticamente |
| `sessionStore` | [`SessionStore`](/docs/es/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Replica las transcripciones de la sesión en un backend externo para que otro host pueda reanudarlas. Consulta [Persistir sesiones en almacenamiento externo](/docs/es/agent-sdk/session-storage) |
| `sessionStoreFlush` | `'batched' \| 'eager'` | `'batched'` | *Alpha.* Modo de vaciado para `sessionStore`. Se ignora cuando `sessionStore` no está establecido |
| `settings` | `string \| Settings` | `undefined` | Objeto de [configuración](/docs/es/settings) en línea, una ruta a un archivo de configuración o una cadena JSON en línea. Rellena la capa de configuración de flags en el [orden de precedencia](/docs/es/settings#settings-precedence). Cámbialo en tiempo de ejecución con [`applyFlagSettings()`](#applyflagsettings) |
| `settingSources` | [`SettingSource`](#settingsource)`[]` | Valores predeterminados de la CLI (todas las fuentes) | Controla qué configuración del sistema de archivos se carga. Pasa `[]` para deshabilitar la configuración de usuario, de proyecto y local. La [política administrada por endpoint](/docs/es/managed-settings#delivery-mechanisms) se carga de todos modos; la configuración administrada por servidor se obtiene cuando la sesión se autentica con una credencial de organización en una [configuración elegible](/docs/es/server-managed-settings#platform-availability). Consulta [Usar funciones de Claude Code](/docs/es/agent-sdk/claude-code-features#what-settingsources-does-not-control) |
| `skills` | `string[] \| 'all'` | `undefined` | Skills disponibles para la sesión. Pasa `'all'` para habilitar todos los skills descubiertos, o una lista de nombres de skills. Pasa solo nombres exactos. En Agent SDK v0.3.221 o posterior, el SDK rechaza con un error los nombres mal formados y con comodines antes de iniciar el proceso de Claude Code. Cuando se establece, el SDK agrega automáticamente la herramienta Skill a `allowedTools`. Si también pasas `tools`, incluye `'Skill'` en esa lista. Consulta [Skills](/docs/es/agent-sdk/skills) |
| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Función personalizada para generar el proceso de Claude Code. Úsala para ejecutar Claude Code en VMs, contenedores o entornos remotos |
| `stderr` | `(data: string) => void` | `undefined` | Callback para la salida de stderr |
| `strictMcpConfig` | `boolean` | `false` | Usa solo los servidores pasados en `mcpServers` e ignora el `.mcp.json` del proyecto, la configuración de usuario, los servidores MCP proporcionados por plugins y los [conectores de claude.ai](/docs/es/mcp#use-mcp-servers-from-claude-ai) |
| `systemPrompt` | `string \| string[] \| { type: 'custom'; prompt: string \| string[]; snapshot?: boolean } \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean; snapshot?: boolean }` | `undefined` (prompt mínimo) | Configuración del prompt del sistema. Pasa una cadena para un prompt personalizado, o `{ type: 'preset', preset: 'claude_code' }` para usar el prompt del sistema de Claude Code. Pasa un array de cadenas con la constante exportada `SYSTEM_PROMPT_DYNAMIC_BOUNDARY` entre la parte estática y la parte por solicitud para [almacenar en caché la parte estática de un prompt personalizado](/docs/es/agent-sdk/modifying-system-prompts#cache-the-static-part-of-a-custom-prompt). Al usar la forma de objeto preset, agrega `append` para ampliarlo con instrucciones adicionales, y establece `excludeDynamicSections: true` para mover el contexto por sesión al primer mensaje del usuario y así [reutilizar mejor la caché de prompts entre máquinas](/docs/es/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines). Establece `snapshot: false` para reconstruir el prompt en cada solicitud en lugar de [reutilizar el prompt que la sesión registró en su primera solicitud](/docs/es/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session). Para establecer `snapshot` en un prompt personalizado, pasa la forma `{ type: 'custom', prompt }`. La forma `{ type: 'custom' }` y el campo `snapshot` requieren TypeScript Agent SDK v0.3.257 o posterior |
| `taskBudget` | `{ total: number }` | `undefined` | *Alpha.* Presupuesto de tarea del lado de la API, en tokens. Cuando se establece, se le indica al modelo su presupuesto de tokens restante para que pueda dosificar el uso de herramientas y terminar antes del límite |
| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` para los modelos compatibles | Controla el comportamiento de pensamiento/razonamiento de Claude. Consulta [`ThinkingConfig`](#thinkingconfig) para ver las opciones |
| `title` | `string` | `undefined` | Título que se muestra para la sesión. Al reanudar mediante `resume` o `continue`, el título persistido de la sesión reanudada tiene precedencia; usa [`renameSession()`](#renamesession) para cambiar el título de una sesión existente |
| `toolAliases` | `Record<string, string>` | `undefined` | Asigna nombres de herramientas integradas a nombres de herramientas MCP para que Claude llame a tu implementación MCP en lugar de la integrada. Por ejemplo, `{ Bash: 'mcp__workspace__bash' }` |
| `toolConfig` | [`ToolConfig`](#toolconfig) | `undefined` | Configuración del comportamiento de las herramientas integradas. Consulta [`ToolConfig`](#toolconfig) para más detalles |
| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuración de herramientas. Pasa un array de nombres de herramientas o usa el preset para obtener las herramientas predeterminadas de Claude Code |
| `verbatimPrompts` | `boolean` | `false` | Entrega cada prompt tal como está escrito. El SDK envía cada mensaje del usuario con `client_composed: true`. Consulta [`client_composed`](#sdkusermessage) para ver qué omite Claude Code en esos mensajes. Usa esta opción cuando el texto de tu prompt incluya contenido que el usuario final no escribió. Para controlarlo por turno, déjala desactivada y establece `client_composed` en mensajes individuales enviados en streaming. Requiere TypeScript Agent SDK v0.3.280 o posterior y Claude Code v2.1.248 o posterior; la versión de Claude Code incluida con esas versiones del SDK cumple el requisito de Claude Code |

<h4 id="handle-slow-or-stalled-api-responses">
  Manejar respuestas de API lentas o detenidas
</h4>

El subproceso de la CLI lee varias variables de entorno que controlan los tiempos de espera de la API y la detección de bloqueos. Pásalas mediante la opción `env`:

```typescript theme={null}
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. Valor predeterminado: `10`, con un límite de `15`. Cada reintento tiene su propia ventana de `API_TIMEOUT_MS`, por lo que el tiempo real en el peor caso es aproximadamente `API_TIMEOUT_MS × (CLAUDE_CODE_MAX_RETRIES + 1)` más el tiempo de backoff. Para ejecuciones desatendidas que necesitan esperar durante interrupciones más largas, establece [`CLAUDE_CODE_RETRY_WATCHDOG=1`](/docs/es/errors#tune-retry-behavior): 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 era siempre `600000`.

  El temporizador se reinicia con cada evento del stream. Ante un bloqueo, Claude Code aborta el subagente e informa del bloqueo al agente principal. 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 un valor predeterminado de `300000` y no puede ser inferior a ese mínimo. Después del aborto, [Reintentos automáticos](/docs/es/errors#automatic-retries) explica qué 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 del stream](#sdkpartialassistantmessage) `ping`, así que interpreta esos frames como señal de actividad en lugar de agotar el tiempo de la sesión por silencio. Antes de v2.1.257, los frames se detenían 5 minutos después del último evento real del stream.

<h3 id="query-object">
  Objeto `Query`
</h3>

Interfaz que devuelve la función `query()`.

```typescript theme={null}
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;
}
```

<h4 id="methods">
  Métodos
</h4>

| Método | Descripción |
| :- | :- |
| `interrupt()` | Interrumpe la consulta. Solo está disponible en el modo de entrada en streaming. Cuando la CLI anuncia la capacidad `interrupt_receipt_v1` en [`SDKSystemMessage.capabilities`](#sdksystemmessage), se resuelve con un [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) que enumera los mensajes que estaban pendientes cuando llegó la interrupción. Se resuelve con `undefined` en CLIs anteriores a v2.1.205 |
| `rewindFiles(userMessageId, options?)` | Restaura los archivos al estado que tenían en el mensaje de usuario especificado. Pasa `{ dryRun: true }` para previsualizar los cambios. Requiere `enableFileCheckpointing: true`. Consulta [Checkpointing de archivos](/docs/es/agent-sdk/file-checkpointing) |
| `setPermissionMode()` | Cambia el modo de permisos (solo disponible en el modo de entrada en streaming) |
| `setModel()` | Cambia el modelo (solo disponible en el modo de entrada en streaming). Pasar `undefined` o la cadena `"default"` restablece el [modelo predeterminado de Claude Code](/docs/es/model-config) |
| `setMaxThinkingTokens()` | *Obsoleto:* usa la opción `thinking` en su lugar. Cambia el máximo de tokens de pensamiento. Pasar `null` restablece el pensamiento al valor predeterminado de la sesión: se borra cualquier sobrescritura hecha a mitad de sesión, y el pensamiento sigue desactivado en las sesiones que lo tienen deshabilitado |
| `applyFlagSettings(settings)` | Combina ajustes en la capa de configuración de flags de la sesión en tiempo de ejecución (solo disponible en el modo de entrada en streaming). Consulta [`applyFlagSettings()`](#applyflagsettings) |
| `updateSettings(source, settings)` | Escribe una clave permitida en el archivo de configuración local del proyecto o en tu archivo de configuración de usuario, para que el valor persista en sesiones posteriores. Consulta [`updateSettings()`](#updatesettings). Requiere TypeScript SDK v0.3.257 o posterior, que incluye Claude Code v2.1.257 |
| `initializationResult()` | Devuelve el resultado completo de la inicialización, incluidos los comandos compatibles, los modelos, la información de la cuenta y la configuración del estilo de salida |
| `reinitialize()` | Vuelve a enviar la solicitud de control `initialize` a la CLI en ejecución y devuelve un resultado nuevo en lugar del resultado de la primera conexión almacenado en caché. Úsalo después de una interrupción del transporte, por ejemplo al volver a conectarte a una sesión tras una desconexión, para que las solicitudes de permiso pendientes vuelvan a llegar a tu callback `canUseTool`. Haz que el callback sea idempotente por ID de solicitud, porque una solicitud cuya respuesta se perdió se despacha de nuevo. Requiere Claude Code v2.1.195 o posterior |
| `supportedCommands()` | Devuelve los comandos disponibles. A partir de Agent SDK v0.3.216, la lista refleja los cambios de comandos a mitad de sesión; consulta [`SDKCommandsChangedMessage`](#sdkcommandschangedmessage) |
| `supportedModels()` | Devuelve los modelos disponibles con información para mostrar |
| `supportedAgents()` | Devuelve los subagentes disponibles como [`AgentInfo`](#agentinfo)`[]` |
| `mcpServerStatus()` | Devuelve el estado de los servidores MCP conectados como [`McpServerStatus`](#mcpserverstatus)`[]` |
| `getContextUsage(opts?)` | Devuelve un [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse) que desglosa el uso de la ventana de contexto de la sesión por categoría, skill y herramienta. Con el `detail` predeterminado, son los mismos datos que muestra `/context` en una sesión interactiva, calculados con solicitudes de API de conteo de tokens que no aparecen en el flujo de mensajes; consulta [cómo se manejan estas solicitudes](#sdkcontrolgetcontextusageresponse). La [opción `detail`](#sdkcontrolgetcontextusageresponse) requiere Agent SDK v0.3.257 o posterior |
| `readFile(path, options?)` | Lee un archivo del sistema de archivos de la sesión. Claude Code resuelve la ruta con respecto a `cwd`; [Qué puede leer `readFile()`](#what-readfile-can-read) enumera los archivos que sirve. Pasa `{ maxBytes }` para cambiar el límite de lectura (1 MB de forma predeterminada, 10 MB como máximo) y `{ encoding: 'base64' }` para archivos binarios como imágenes. Se resuelve con un [`SDKControlReadFileResponse`](#sdkcontrolreadfileresponse), o con `null` ante una denegación de permiso, un archivo inexistente o un error de transporte. Requiere TypeScript SDK v0.2.121 o posterior |
| `reloadPlugins(options?)` | Vuelve a cargar los plugins desde el disco, para que los plugins que instales o edites a mitad de sesión lleguen a la sesión en ejecución. Se resuelve con un [`SDKControlReloadPluginsResponse`](#sdkcontrolreloadpluginsresponse) que enumera los comandos, subagentes, plugins y el estado de los servidores MCP de la sesión. Requiere Agent SDK v0.2.85 o posterior. La [opción `holdOnCacheImpact`](#sdkcontrolreloadpluginsresponse) requiere Agent SDK v0.3.268 o posterior |
| `reloadSkills()` | Vuelve a cargar los skills desde el disco, para que los skills que agregues o edites a mitad de sesión estén disponibles para la sesión en ejecución. Se resuelve con un [`SDKControlReloadSkillsResponse`](#sdkcontrolreloadskillsresponse) que enumera los skills disponibles después de la recarga. Requiere Agent SDK v0.3.163 o posterior |
| `reloadOutputStyles()` | Vuelve a leer los [estilos de salida](/docs/es/output-styles) desde el disco, para que un archivo de estilo que agregues o edites a mitad de sesión esté disponible para la sesión en ejecución. Se resuelve con un [`SDKControlReloadOutputStylesResponse`](#sdkcontrolreloadoutputstylesresponse) que enumera los nombres de los estilos disponibles después de la recarga. Requiere Agent SDK v0.3.261 o posterior |
| `accountInfo()` | Devuelve la información de la cuenta |
| `reconnectMcpServer(serverName)` | Vuelve a conectar un servidor MCP por nombre. Si el nombre también coincide con una entrada de un archivo de configuración como `.mcp.json` o `~/.claude.json`, Claude Code vuelve a conectar el servidor que configuraste mediante [`mcpServers`](#options) o `setMcpServers()`, no la entrada del archivo de configuración. Ese orden de resolución requiere Claude Code v2.1.257 o posterior |
| `toggleMcpServer(serverName, enabled)` | Habilita o deshabilita un servidor MCP por nombre, con la misma resolución de nombres que `reconnectMcpServer()`. Deshabilitar un servidor lo desconecta y elimina sus herramientas. Consulta [`toggleMcpServer()`](#togglemcpserver) para ver la versión de Claude Code que esto necesita para cada tipo de servidor |
| `setMcpServers(servers)` | Reemplaza dinámicamente el conjunto de servidores MCP de esta sesión. Se resuelve con un [`McpSetServersResult`](#mcpsetserversresult) que indica qué servidores se agregaron y cuáles se eliminaron, además de los errores |
| `readMcpResource(serverName, uri)` | *Alpha.* Lee un recurso `ui://` de MCP Apps de un servidor MCP conectado para que tu aplicación pueda renderizar el widget de una herramienta. Se resuelve con un [`SDKControlMcpReadResourceResponse`](#sdkcontrolmcpreadresourceresponse). Requiere TypeScript Agent SDK v0.3.280 o posterior |
| `streamInput(stream)` | Envía en streaming mensajes de entrada a la consulta para conversaciones de varios turnos |
| `stopTask(taskId)` | Detiene una tarea en segundo plano en ejecución por su ID |
| `close()` | Cierra la consulta y termina el proceso subyacente. Finaliza la consulta de forma forzada y libera todos los recursos |

<h4 id="applyflagsettings">
  `applyFlagSettings()`
</h4>

Cambia la [configuración](/docs/es/settings) de una sesión en ejecución sin reiniciar la consulta. Úsalo cuando un ajuste que no tiene un setter dedicado necesita cambiar a mitad de sesión, por ejemplo para restringir `permissions` después de que el agente lea una entrada que no es de confianza. `setModel()` y `setPermissionMode()` son setters dedicados para esas dos claves; `applyFlagSettings()` es la forma general que acepta cualquier subconjunto de las claves de configuración, y pasar `model` aquí se comporta igual que `setModel()`.

Solo algunas claves surten efecto a mitad de sesión:

* **Se aplican en el siguiente turno**: `effortLevel`, `ultracode`, `permissions`, `hooks`, `skillOverrides`, `fastMode`, `agent`. Cambiar `agent` también aplica en el siguiente turno la sobrescritura de modelo y los hooks de ese agente. Su prompt del sistema se aplica en el siguiente turno o, en una sesión que [reutiliza un prompt del sistema registrado](/docs/es/agent-sdk/modifying-system-prompts#change-the-prompt-of-an-existing-session), una vez que la sesión se compacta.
* **Se aplican durante el turno actual**: `model`. Si cambias `model` mientras Claude trabaja en un turno, la respuesta que Claude ya está generando termina con el modelo anterior, y el resto del turno, empezando por 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 a mitad de 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 se complete correctamente. Para cambiarlas, inicia una nueva sesión.

`effortLevel` acepta el nombre de un [nivel de esfuerzo](/docs/es/model-config#adjust-effort-level). También acepta `"ultracode"`, que solicita el esfuerzo `xhigh` con [ultracode](/docs/es/workflows#let-claude-decide-with-ultracode) activado. `applyFlagSettings()` declara `effortLevel` sin ese valor, así que en TypeScript pasa `{ ultracode: true, effortLevel: "xhigh" }` para obtener el mismo resultado, o solo la clave [`ultracode`](/docs/es/settings-reference#ultracode) para activar ultracode con el nivel de esfuerzo actual de la sesión. El valor `ultracode` requiere Claude Code v2.1.203 o posterior y solo lo acepta `applyFlagSettings()`, no la clave `effortLevel` de un archivo de configuración. Antes de v2.1.284, la clave `ultracode` por sí sola también establecía el nivel en `xhigh`.

Los valores se escriben en la capa de configuración de flags y se combinan sobre lo que estableció al inicio la opción `settings` en línea de `query()`. Es el mismo nivel que la [sección de precedencia de esta página](#settings-precedence) llama opciones programáticas.

Las llamadas sucesivas combinan superficialmente las claves de nivel superior. Una segunda llamada con `{ permissions: {...} }` reemplaza todo el objeto `permissions` de la llamada anterior en lugar de combinarse en profundidad con él.

Para borrar una clave que estableciste con `applyFlagSettings()`, pasa `null` para esa clave. La mayoría de las claves recurren entonces primero a un valor que la opción `settings` de `query()` estableció al inicio y, después, a fuentes de menor precedencia. Un `model` borrado se restablece al [modelo predeterminado de Claude Code](/docs/es/model-config), incluso cuando un archivo de configuración establece `model`. Pasar `undefined` no tiene efecto porque la serialización JSON lo descarta.

Además de `model`, tres claves restablecen el estado de la sesión en lugar de recurrir a otro valor:

* `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 `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.

Solo está disponible en el modo de entrada en streaming, la misma restricción que tienen `setModel()` y `setPermissionMode()`.

El siguiente ejemplo cambia el modelo activo a mitad de sesión y luego borra la sobrescritura para que el modelo se restablezca al [modelo predeterminado de Claude Code](/docs/es/model-config).

```typescript theme={null}
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 });
```

<Note>
  `applyFlagSettings()` solo está disponible en TypeScript. El SDK de Python no expone un método equivalente.
</Note>

<h4 id="updatesettings">
  `updateSettings()`
</h4>

Escribe una clave permitida en un archivo de configuración en disco, para que el valor persista en sesiones posteriores que carguen esa fuente. Cada fuente acepta una clave, con un valor de cadena:

* **`"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 [nivel de esfuerzo](/docs/es/model-config#adjust-effort-level) predeterminado para el modelo actual de la sesión, en [`modelSettings`](/docs/es/settings-reference#modelsettings) dentro de 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()`](#applyflagsettings) si también quieres cambiarlo. Esta fuente requiere TypeScript SDK v0.3.277 o posterior, que incluye Claude Code v2.1.277.

La llamada se rechaza cuando la solicitud contiene cualquier otra clave, cuando la sesión se ejecuta sobre un transporte remoto y cuando los [`settingSources`](#options) de la sesión excluyen la fuente que indicas. No se admite eliminar una clave.

<h4 id="togglemcpserver">
  `toggleMcpServer()`
</h4>

Deshabilitar un servidor lo desconecta y elimina sus herramientas de la sesión. Para los servidores que agregaste a mitad de sesión y para los servidores en proceso, esto depende de tu versión de Claude Code:

* Un servidor stdio, SSE o HTTP que agregaste a mitad de sesión con `setMcpServers()`: eliminar sus herramientas requiere Claude Code v2.1.285 o posterior.
* Un servidor en proceso que creaste con [`createSdkMcpServer()`](#createsdkmcpserver), ya sea que lo pasaras en `mcpServers` o con `setMcpServers()`: desconectarlo y eliminar sus herramientas requiere Claude Code v2.1.286 o posterior. Deshabilitar uno también hace fallar sus llamadas a herramientas que aún se están ejecutando, de modo que Claude recibe de inmediato un resultado de error para cada una, sin esperar a que tu handler termine.

<h3 id="warmquery">
  `WarmQuery`
</h3>

Handle que devuelve [`startup()`](#startup). El subproceso ya está generado e inicializado, por lo que llamar a `query()` en este handle escribe el prompt directamente en un proceso listo, sin latencia de inicio.

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

<h4 id="methods-2">
  Métodos
</h4>

| Método | Descripción |
| :- | :- |
| `query(prompt)` | Envía un prompt al subproceso precalentado y devuelve un [`Query`](#query-object). Solo se puede llamar una vez por `WarmQuery` |
| `close()` | Cierra el subproceso sin enviar un prompt. Úsalo para descartar una consulta precalentada que ya no necesitas |

`WarmQuery` implementa `AsyncDisposable`, por lo que se puede usar con `await using` para la limpieza automática.

<h3 id="spareprocess">
  `SpareProcess`
</h3>

*Alpha.* Handle que devuelve [`prewarm()`](#prewarm): un proceso de Claude Code iniciado que aún no está vinculado a una sesión y que se puede reclamar una vez. Requiere TypeScript Agent SDK v0.3.282 o posterior.

```typescript theme={null}
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;
}
```

<h4 id="members">
  Miembros
</h4>

| Miembro | Descripción |
| :- | :- |
| `claim({ prompt, options })` | Vincula el proceso de reserva a una sesión en `options.cwd` y envía su primer mensaje. Devuelve un [`Query`](#query-object) de forma síncrona, igual que `query()`. Solo se puede llamar una vez |
| `claimed` | Se resuelve con el directorio de trabajo y el ID de la sesión una vez que Claude Code acepta la reclamación. Se rechaza cuando Claude Code rechaza la reclamación, cuando el proceso terminó o se cerró antes y, con un mensaje que empieza por `option_not_applied`, cuando la sesión se está ejecutando sin el `model` o el `maxThinkingTokens` que pediste |
| `exited` | Se resuelve cuando el proceso termina, haya sido reclamado o no. Reemplaza un proceso de reserva que termine antes de que lo reclames |
| `close()` | Termina el proceso. Antes de una reclamación, esto descarta el proceso de reserva y rechaza `claimed` |

`options.cwd` es obligatorio. Una reclamación también puede establecer `additionalDirectories`, `model`, `permissionMode`, `maxThinkingTokens`, una superposición de configuración de flags en `settings`, `appendSystemPrompt`, `title`, `agents` y tokens por sesión en `env`.

Claude Code puede rechazar una reclamación, por ejemplo para una carpeta que no existe o una cuya configuración de proyecto establece `env`, `agent` o `model`. Cuando `claimed` se rechaza con un mensaje que empieza por `option_not_applied`, la sesión se está ejecutando sin el `model` o el `maxThinkingTokens` que pediste. Después de cualquier otro rechazo, tu prompt no se ha ejecutado, así que inicia la sesión con `query()` en su lugar.

<h3 id="sdkcontrolinitializeresponse">
  `SDKControlInitializeResponse`
</h3>

Tipo de retorno de `initializationResult()`. Contiene los datos de inicialización de la sesión.

```typescript theme={null}
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"
  >;
};
```

`hooks_applied` indica si Claude Code registró los `hooks` que contenía la solicitud `initialize`. El SDK envía esa solicitud una vez cuando se inicia la sesión y de nuevo en cada llamada a [`reinitialize()`](#query-object). El campo requiere Agent SDK v0.3.238 o posterior.

Claude Code omite el campo cuando la solicitud no contenía hooks. Cuando la solicitud contenía hooks, el valor depende de si la solicitud es la primera inicialización de la sesión y, en el caso de una repetida, de cómo llegó a la sesión:

* `true`: Claude Code registró los hooks. La primera inicialización de una sesión devuelve este valor. Una inicialización repetida enviada por el stdin de la CLI también devuelve `true`. En ese caso, los hooks de la nueva solicitud reemplazan a los registrados anteriormente.
* `false`: Claude Code ignoró los hooks. Una inicialización repetida enviada 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.

Antes de Agent SDK v0.3.238, la respuesta nunca contenía el campo, y Claude Code ignoraba `hooks` en cada inicialización repetida.

El campo `sdkMcpServerManifests` de la solicitud y el campo `sdk_mcp_manifests_parked` de la respuesta son para los [servidores MCP del SDK](/docs/es/agent-sdk/custom-tools) en proceso que creaste con [`createSdkMcpServer()`](#createsdkmcpserver). Tu aplicación no establece ni lee ninguno de los dos campos.

La respuesta siempre informa `fast_mode_state` y, cuando algo bloquea el [modo rápido](/docs/es/fast-mode), `fast_mode_disabled_reason` contiene el código del motivo junto a él, para que puedas explicar el estado bloqueado en lugar de volver a deducir la disponibilidad. Ambos comportamientos requieren Claude Code v2.1.219 o posterior. Antes de v2.1.219, la respuesta omitía `fast_mode_state` cuando el modo rápido no estaba disponible y nunca incluía un motivo. Para ver los códigos de motivo y su significado, consulta [`fast_mode_disabled_reason`](#sdkresultmessage) en el mensaje de resultado.

El contenedor de respuesta de control de un `initialize` correcto también contiene un array `pending_permission_requests`. El campo está en el propio contenedor de la respuesta, no en el payload `SDKControlInitializeResponse` anterior. Cada entrada es un mensaje `control_request` completo con la misma forma `{ type: "control_request", request_id, request }` que la sesión transmite en streaming para las solicitudes de permiso mientras se ejecuta.

El array enumera las solicitudes de permiso que este proceso de Claude Code ha emitido y aún no ha resuelto. El SDK lee el array por ti y despacha cada entrada a tu callback [`canUseTool`](#canusetool), la misma reentrega que desencadena [`reinitialize()`](#query-object) después de una interrupción del transporte. Maneja los IDs de solicitud repetidos de forma idempotente, porque una entrada puede repetir una solicitud que el callback ya recibió antes de que se cayera la conexión.

El array siempre está presente en una respuesta `initialize` correcta y está vacío cuando este proceso no tiene solicitudes de permiso sin resolver. Requiere Claude Code v2.1.268 o posterior. Las versiones anteriores podían omitir el campo, así que si analizas el protocolo de comunicación por tu cuenta, trata un campo ausente como señal de una CLI más antigua y no como prueba de que no hay nada pendiente.

<h3 id="sdkcontrolinterruptresponse">
  `SDKControlInterruptResponse`
</h3>

El recibo de interrupción: el valor con el que se resuelve [`interrupt()`](#query-object) en una CLI que anuncia la capacidad `interrupt_receipt_v1` en [`SDKSystemMessage.capabilities`](#sdksystemmessage). Requiere Claude Code v2.1.205 o posterior. Las CLIs anteriores responden a la interrupción con un payload de éxito vacío, por lo que `interrupt()` se resuelve con `undefined`.

```typescript theme={null}
type SDKControlInterruptResponse = {
  still_queued: string[];
  cancelled?: string[];
};
```

`still_queued` enumera los UUIDs de los mensajes del usuario que estaban pendientes cuando llegó la interrupción: los mensajes que seguían en la cola, más los que Claude Code ya había sacado de la cola para el siguiente turno. Una vez iniciado el primer turno de la sesión, Claude Code procesa los mensajes listados después de la interrupción, a menos que los canceles antes, y puede combinar varios en un solo turno. Si interrumpes antes de que empiece el primer turno, Claude Code aborta ese turno en cuanto empieza, y los mensajes listados en ese turno no reciben respuesta.

Usa el recibo para decidir si reenvías algo. Un mensaje listado que no canceles entra en la conversación reciba o no una respuesta, así que reenviarlo hace que le llegue a Claude dos veces.

Interpreta la lista teniendo en cuenta estas advertencias:

* 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 UUIDs que tu cliente nunca envió, como los disparadores de [tareas programadas](/docs/es/scheduled-tasks). Ignora los UUIDs que no reconozcas en lugar de tratarlos como un error.

Un cliente que controla directamente el protocolo de control de la CLI, en lugar de hacerlo mediante `interrupt()`, puede establecer `cancel_queued: true` en la solicitud de control `interrupt`. Claude Code v2.1.219 y posteriores anuncian la compatibilidad con la capacidad `interrupt_cancel_queued_v1` en [`SDKSystemMessage.capabilities`](#sdksystemmessage); las CLIs anteriores ignoran el campo y dejan que los mensajes en cola se ejecuten como de costumbre. Una interrupción así también cancela todos los mensajes que de otro modo se listarían en `still_queued`: el recibo los enumera en `cancelled`, `still_queued` queda vacío y ninguno de ellos se ejecuta.

La lista `cancelled` tiene las mismas advertencias que `still_queued`. El método `interrupt()` nunca envía `cancel_queued`, por lo que los recibos con los que se resuelve no contienen `cancelled`.

El recibo es una instantánea tomada en el momento en que se procesa la interrupción y, en una interrupción limpia, llega antes del [`SDKResultMessage`](#sdkresultmessage) del turno interrumpido. Lee el recibo en lugar de inspeccionar la cola después de ese resultado: el bucle inicia inmediatamente el siguiente turno en cola, así que la cola que inspeccionas después del resultado ya ha cambiado.

<h3 id="sdkcontrolgetcontextusageresponse">
  `SDKControlGetContextUsageResponse`
</h3>

Tipo de retorno de [`getContextUsage()`](#query-object). Con el `detail` predeterminado, es el mismo payload que Claude Code renderiza para el comando `/context` en una sesión interactiva, así que, junto con los conteos de tokens, contiene campos de visualización como `color` y `gridRows` que Claude Code usa para dibujar la cuadrícula de uso de `/context`.

El argumento opcional `detail` del método elige cómo cuenta Claude Code cada categoría. El argumento `detail` requiere Agent SDK v0.3.257 o posterior.

* **`'full'`**: el valor predeterminado. Claude Code cuenta cada categoría con solicitudes de API de [conteo de tokens](https://platform.claude.com/docs/en/build-with-claude/token-counting). Estas solicitudes no aparecen en el flujo de mensajes, así que un seguimiento de costos que lea el flujo no las verá. En la API de Anthropic, el conteo de tokens no se factura.
* **`'summary'`**: pasa `{ detail: 'summary' }` para obtener una respuesta basada en el uso de la última respuesta y en estimaciones locales. No se envían solicitudes de conteo de tokens, y los números por categoría son aproximados.

Cuando envías `/context` como prompt en lugar de llamar al método, Claude Code adjunta un payload [`SDKContextUsage`](#sdkcontextusage) al campo `context_usage` del mensaje del asistente que entrega el resultado. Ese campo requiere Agent SDK v0.3.232 o posterior.

```typescript theme={null}
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;
};
```

Lee la atribución de tokens en los campos de colección:

* `categories` contiene los totales por categoría. El campo `kind` de cada entrada clasifica la fila con los mismos valores que [`SDKContextUsageCategory`](#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 entraron en el listado.

`totalTokens` es el uso de contexto actual de la sesión, y `maxTokens` es la ventana con respecto a la cual se mide ese uso. Esa ventana es la ventana de contexto del modelo, o la ventana de compactación automática, más baja, cuando corresponde. `rawMaxTokens` contiene el mismo valor que `maxTokens`, y `percentage` es `totalTokens` como porcentaje redondeado de esa ventana. `apiUsage` contiene el uso de la última respuesta de la API, no un total acumulado de la sesión.

Claude Code deja sin establecer los diagnósticos opcionales `deferredBuiltinTools`, `systemTools` y `systemPromptSections`, así que espera que estén ausentes aunque el tipo los declare.

<h3 id="sdkcontrolreadfileresponse">
  `SDKControlReadFileResponse`
</h3>

Tipo de retorno de [`readFile()`](#query-object).

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

`contents` contiene el texto del archivo, o datos en base64 cuando solicitaste `encoding: 'base64'`; en ese caso, el campo `encoding` de la respuesta se establece en `'base64'`. `absPath` es la ruta absoluta resuelta. `truncated` se establece cuando el archivo era más largo que el límite `maxBytes` y el contenido se cortó en ese límite.

<h4 id="what-readfile-can-read">
  Qué puede leer `readFile()`
</h4>

`readFile()` sirve un conjunto de archivos más reducido que la herramienta Read:

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

Las reglas de denegación y de consulta de `Read` siguen bloqueando una ruta coincidente, y una regla de permiso amplia de `Read` no abre el resto del sistema de archivos a `readFile()`. Para cualquier otra cosa, la llamada se resuelve con `null`.

<h3 id="sdkcontrolreloadpluginsresponse">
  `SDKControlReloadPluginsResponse`
</h3>

Tipo de retorno de [`reloadPlugins()`](#query-object).

```typescript theme={null}
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;
  };
};
```

Los campos de colección describen la sesión después de la llamada:

* `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 durante la inicialización, así que lee aquí `agents` 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

Pasa `{ holdOnCacheImpact: true }` a `reloadPlugins()` para retener una recarga que invalidaría la caché de prompts de la conversación en lugar de aplicarla. Claude Code ejecuta la misma comprobación que hace el comando interactivo `/reload-plugins` antes de [advertir sobre el costo para la caché](/docs/es/prompt-caching#enabling-or-disabling-a-plugin). La opción requiere Agent SDK v0.3.268 o posterior. Un ejecutable de Claude Code anterior a v2.1.268, como uno al que apuntes con `pathToClaudeCodeExecutable`, ignora la opción y aplica la recarga.

Cuando pasas la opción, lee `held` para saber qué ocurrió:

* `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.

`cache_impact` solo está presente junto con `held: true`. `mcp_servers_added` y `mcp_servers_removed` nombran los servidores MCP de plugins que la recarga registraría o eliminaría, como nombres con alcance `plugin:<plugin>:<server>`. Los nombres los define el autor del plugin, así que valídalos antes de mostrarlos. `lsp_tool_change` indica si aplicar la recarga agregaría o eliminaría la herramienta LSP, o `null` cuando no haría ninguna de las dos cosas. Las formas `may-` significan que la comprobación no pudo ver por completo el conjunto de plugins pendiente.

<h3 id="sdkcontrolreloadskillsresponse">
  `SDKControlReloadSkillsResponse`
</h3>

Tipo de retorno de [`reloadSkills()`](#query-object).

```typescript theme={null}
type SDKControlReloadSkillsResponse = {
  skills: SlashCommand[];
};
```

`skills` enumera los skills disponibles después de la recarga, con la misma forma [`SlashCommand`](#slashcommand) que devuelve `supportedCommands()`.

<h3 id="sdkcontrolreloadoutputstylesresponse">
  `SDKControlReloadOutputStylesResponse`
</h3>

Tipo de retorno de [`reloadOutputStyles()`](#query-object).

```typescript theme={null}
type SDKControlReloadOutputStylesResponse = {
  available_output_styles: string[];
};
```

`available_output_styles` enumera los nombres de los estilos de salida integrados y personalizados disponibles después de la recarga.

<h3 id="sdkcontrolmcpreadresourceresponse">
  `SDKControlMcpReadResourceResponse`
</h3>

Tipo de retorno de [`readMcpResource()`](#query-object), que contiene el resultado de `resources/read` del servidor MCP. Requiere TypeScript Agent SDK v0.3.280 o posterior.

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

Pasa a `readMcpResource()` el nombre del servidor tal como lo informa `mcpServerStatus()` y un URI `ui://`, como el `ui.resourceUri` que una herramienta declara en su [`_meta`](#mcpserverstatus). La llamada se rechaza para cualquier otro esquema de URI, para un [servidor MCP del SDK](#createsdkmcpserver) que tu aplicación aloja por sí misma y para un servidor que no está conectado. Está disponible cuando las [`capabilities`](#sdksystemmessage) del mensaje de inicialización incluyen `mcp_read_resource_v1`.

Cada entrada de `contents` es un elemento de contenido tal como lo envió el servidor, sin ninguna clave `_meta` bajo el prefijo `com.anthropic/`, que está reservado para Claude Code. `blob` contiene datos en base64 para un elemento binario, y `_meta` es el `_meta` propio del elemento, donde un servidor de MCP Apps coloca los valores `ui.csp` y `ui.permissions` del recurso.

El contenido es HTML de terceros que no es de confianza, así que renderízalo en un sandbox.

<h3 id="agentdefinition">
  `AgentDefinition`
</h3>

Configuración de un subagente definido mediante programación.

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

| Campo | Obligatorio | Descripción |
| :- | :- | :- |
| `description` | Sí | Descripción en lenguaje natural de cuándo usar este agente |
| `tools` | No | Array de nombres de herramientas permitidas. Si se omite, hereda todas las [herramientas disponibles para los subagentes](/docs/es/sub-agents#available-tools). Para precargar Skills en el contexto del agente, usa el campo `skills` en lugar de listar `'Skill'` aquí |
| `disallowedTools` | No | Array de nombres de herramientas que se prohíben explícitamente para este agente. También se aceptan patrones a nivel de servidor MCP: `mcp__server` o `mcp__server__*` elimina todas las herramientas de ese servidor, y `mcp__*` elimina todas las herramientas MCP de cualquier servidor |
| `prompt` | Sí | El prompt del sistema del agente |
| `model` | No | Sobrescritura del modelo para este agente. Acepta un alias como `'fable'`, `'opus'`, `'sonnet'`, `'haiku'`, `'inherit'`, o un ID de modelo completo. `'inherit'` usa el modelo principal. Si lo omites, Claude Code elige el modelo según el [orden de modelos de los subagentes](/docs/es/sub-agents#choose-a-model) |
| `mcpServers` | No | Especificaciones de servidores MCP para este agente |
| `skills` | No | Array de nombres de skills que se precargan en el contexto del agente |
| `initialPrompt` | No | Se envía automáticamente como el primer turno del usuario cuando este agente se ejecuta como agente del hilo principal |
| `maxTurns` | No | Número máximo de turnos agénticos (idas y vueltas a la API) antes de detenerse |
| `background` | No | Ejecuta este agente como una tarea en segundo plano no bloqueante cuando se invoca |
| `omitClaudeMd` | No | Ejecuta este agente sin los archivos CLAUDE.md de usuario, de proyecto y locales cuando se ejecuta como subagente; los archivos de política administrada se siguen cargando. Úsalo para agentes que obtienen todo lo que necesitan del prompt de la herramienta Agent. Se ignora cuando este agente se ejecuta como agente del hilo principal. Requiere TypeScript Agent SDK v0.3.271 o posterior |
| `memory` | No | Fuente de memoria para este agente: `'user'`, `'project'` o `'local'` |
| `effort` | No | Nivel de esfuerzo de razonamiento para este agente. Acepta un nivel con nombre o un entero |
| `permissionMode` | No | Modo de permisos para la ejecución de herramientas dentro de este agente. Las [reglas de herencia de los subagentes](/docs/es/agent-sdk/permissions#available-modes) deciden cuándo se aplica. Consulta [`PermissionMode`](#permissionmode) |
| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: recordatorio crítico que se agrega al prompt del sistema |

<h3 id="agentmcpserverspec">
  `AgentMcpServerSpec`
</h3>

Especifica los servidores MCP disponibles para un subagente. Puede ser un nombre de servidor (una cadena que hace referencia a un servidor de la configuración `mcpServers` del agente principal) o un registro de configuración de servidores en línea que asigna nombres de servidores a configuraciones.

```typescript theme={null}
type AgentMcpServerSpec = string | Record<string, McpServerConfigForProcessTransport>;
```

Donde `McpServerConfigForProcessTransport` es `McpStdioServerConfig | McpSSEServerConfig | McpHttpServerConfig | McpSdkServerConfig`.

<h3 id="settingsource">
  `SettingSource`
</h3>

Controla desde qué fuentes de configuración basadas en el sistema de archivos carga la configuración el SDK.

```typescript theme={null}
type SettingSource = "user" | "project" | "local";
```

| Valor | Descripción | Ubicación |
| :- | :- | :- |
| `'user'` | Configuración global del usuario | `~/.claude/settings.json` |
| `'project'` | Configuración compartida del proyecto (bajo control de versiones) | `.claude/settings.json` |
| `'local'` | Configuración local del proyecto, incluida en gitignore cuando Claude Code guarda un ajuste en ella | `.claude/settings.local.json` |

<h4 id="default-behavior">
  Comportamiento predeterminado
</h4>

Cuando `settingSources` se omite o es `undefined`, `query()` carga la misma configuración del sistema de archivos que la CLI de Claude Code: user, project y local. Consulta [Lo que settingSources no controla](/docs/es/agent-sdk/claude-code-features#what-settingsources-does-not-control) para ver las entradas que se leen independientemente de esta opción y cómo desactivarlas.

<h4 id="why-use-settingsources">
  Por qué usar settingSources
</h4>

**Desactivar la configuración del sistema de archivos:**

```typescript theme={null}
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: [] }
});
```

**Cargar solo fuentes de configuración específicas:**

```typescript theme={null}
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
  }
});
```

Para cargar las instrucciones de proyecto de CLAUDE.md, incluye `"project"` en `settingSources`. Consulta [Modificar prompts del sistema](/docs/es/agent-sdk/modifying-system-prompts#claude-md-files-for-project-level-instructions) para ver cómo interactúa la carga de CLAUDE.md con las opciones del prompt del sistema.

<h4 id="settings-precedence">
  Precedencia de la configuración
</h4>

Cuando se cargan varias fuentes, la configuración se combina con esta precedencia (de mayor a menor):

1. Configuración local (`.claude/settings.local.json`)
2. Configuración del proyecto (`.claude/settings.json`)
3. Configuración del usuario (`~/.claude/settings.json`)

Las opciones programáticas como `agents`, `allowedTools` y `settings` sobrescriben la configuración del sistema de archivos de user, project y local. La configuración de políticas administradas tiene precedencia sobre las opciones programáticas.

<h3 id="permissionmode">
  `PermissionMode`
</h3>

```typescript theme={null}
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
```

<h3 id="canusetool">
  `CanUseTool`
</h3>

Tipo de función de permisos personalizada para controlar el uso de herramientas.

La función es el reemplazo del SDK para la solicitud de permiso interactiva: solo se invoca cuando el [flujo de evaluación de permisos](/docs/es/agent-sdk/permissions#how-permissions-are-evaluated) termina en una solicitud. Las llamadas a herramientas ya aprobadas por una entrada de `allowedTools`, una regla allow de la configuración o el modo de permisos, como `acceptEdits` o `bypassPermissions`, nunca la invocan. Para controlar cada llamada a herramienta, usa en su lugar un [hook `PreToolUse`](/docs/es/agent-sdk/hooks).

Una regla allow no aprueba previamente las [acciones que ningún modo aprueba automáticamente](/docs/es/permission-modes#actions-no-mode-auto-approves); consulta [Cómo se evalúan los permisos](/docs/es/agent-sdk/permissions#how-permissions-are-evaluated) para saber cuáles de ellas llegan al callback y qué ocurre en los modos `dontAsk` y `auto`.

```typescript theme={null}
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>;
```

| Opción | Tipo | Descripción |
| :- | :- | :- |
| `signal` | `AbortSignal` | Se activa si la operación debe abortarse |
| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Actualizaciones de permisos sugeridas para que no se vuelva a pedir permiso al usuario para esta herramienta. Las solicitudes de Bash incluyen una sugerencia con el [destino](#permissionupdatedestination) `localSettings`, por lo que devolverla en `updatedPermissions` escribe la regla en `.claude/settings.local.json` y persiste entre sesiones. |
| `blockedPath` | `string` | La ruta de archivo que activó la solicitud de permiso, si corresponde |
| `mcpServer` | `{ name: string; source: string }` | Para una herramienta `mcp__*`, el servidor MCP que la proporciona y de dónde proviene la definición de ese servidor, con los campos de [`McpServerProvenance`](#mcpserverprovenance). Ausente para otras herramientas. Requiere Agent SDK v0.3.274 o posterior |
| `decisionReason` | `string` | Explica por qué se activó esta solicitud de permiso |
| `defaultToNo` | `boolean` | Cuando es `true`, una sola pulsación accidental no debe aprobar esta solicitud: abre tu solicitud en su opción de rechazo, no preselecciones la aprobación y no ofrezcas ningún atajo de aprobación de una sola tecla. Requiere Agent SDK v0.3.268 o posterior |
| `suppressAlwaysAllowRule` | `boolean` | Cuando es `true`, no ofrezcas una opción persistente de permitir siempre para esta solicitud, porque la regla que escribiría concede más que la propia acción de la solicitud. Requiere Agent SDK v0.3.268 o posterior |
| `toolUseID` | `string` | Identificador único de esta llamada a herramienta específica dentro del mensaje del asistente |
| `agentID` | `string` | Si se ejecuta dentro de un subagente, el ID del subagente |
| `requestId` | `string` | El `request_id` del sobre `control_request`. Un `control_response` que tu aplicación envíe fuera del SDK, como un HTTP POST firmado, debe repetir este valor para que el proceso de Claude Code pueda asociar la respuesta con la solicitud |

Normalmente, el callback resuelve la solicitud devolviendo un [`PermissionResult`](#permissionresult), que el SDK escribe de vuelta a través de su transporte como el `control_response`. Devuelve `null` solo cuando tu aplicación ya haya enviado el `control_response` para esta solicitud por su propio canal, repitiendo `requestId`; el SDK entonces omite escribir la respuesta en su transporte. Devolver `null` en cualquier otro caso deja la llamada a herramienta bloqueada indefinidamente, porque nunca se envía ningún `control_response` y las solicitudes de permiso no tienen tiempo de espera.

La opción `requestId` y el valor de retorno `null` requieren Claude Code v2.1.199 o posterior.

<h3 id="permissionresult">
  `PermissionResult`
</h3>

Resultado de una verificación de permisos.

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

<h3 id="toolconfig">
  `ToolConfig`
</h3>

Configuración del comportamiento de las herramientas integradas.

```typescript theme={null}
type ToolConfig = {
  askUserQuestion?: {
    previewFormat?: "markdown" | "html";
  };
};
```

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `askUserQuestion.previewFormat` | `'markdown' \| 'html'` | Habilita el campo `preview` en las opciones de [`AskUserQuestion`](/docs/es/agent-sdk/user-input#question-format) y establece el formato de su contenido. Cuando no está definido, Claude no emite vistas previas |

<h3 id="mcpserverconfig">
  `McpServerConfig`
</h3>

Configuración para servidores MCP.

```typescript theme={null}
type McpServerConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfigWithInstance;
```

<h4 id="mcpstdioserverconfig">
  `McpStdioServerConfig`
</h4>

```typescript theme={null}
type McpStdioServerConfig = {
  type?: "stdio";
  command: string;
  args?: string[];
  env?: Record<string, string>;
};
```

<h4 id="mcpsseserverconfig">
  `McpSSEServerConfig`
</h4>

```typescript theme={null}
type McpSSEServerConfig = {
  type: "sse";
  url: string;
  headers?: Record<string, string>;
};
```

<h4 id="mcphttpserverconfig">
  `McpHttpServerConfig`
</h4>

```typescript theme={null}
type McpHttpServerConfig = {
  type: "http";
  url: string;
  headers?: Record<string, string>;
};
```

<h4 id="mcpsdkserverconfigwithinstance">
  `McpSdkServerConfigWithInstance`
</h4>

```typescript theme={null}
type McpSdkServerConfigWithInstance = {
  type: "sdk";
  name: string;
  timeout?: number;
  instance: McpServer;
};
```

<h4 id="mcpclaudeaiproxyserverconfig">
  `McpClaudeAIProxyServerConfig`
</h4>

```typescript theme={null}
type McpClaudeAIProxyServerConfig = {
  type: "claudeai-proxy";
  url: string;
  id: string;
};
```

<h3 id="sdkpluginconfig">
  `SdkPluginConfig`
</h3>

Configuración para cargar plugins en el SDK.

```typescript theme={null}
type SdkPluginConfig = {
  type: "local";
  path: string;
  skipMcpDiscovery?: boolean;
};
```

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `type` | `'local'` | Debe ser `'local'` (actualmente solo se admiten plugins locales) |
| `path` | `string` | Ruta absoluta o relativa al directorio del plugin |
| `skipMcpDiscovery` | `boolean` | Cuando es `true`, el SDK carga los skills, hooks, agentes y comandos de este plugin, pero no lee su `.mcp.json` ni los `mcpServers` del manifiesto. Establécelo cuando tu aplicación gestione las conexiones MCP del plugin. |

**Ejemplo:**

```typescript theme={null}
plugins: [
  { type: "local", path: "./my-plugin" },
  { type: "local", path: "/absolute/path/to/plugin" }
];
```

Para obtener información completa sobre cómo crear y usar plugins, consulta [Plugins](/docs/es/agent-sdk/plugins).

<h2 id="message-types">
  Tipos de Mensajes
</h2>

<h3 id="sdkmessage">
  `SDKMessage`
</h3>

Tipo de unión de todos los mensajes posibles devueltos por la consulta.

```typescript theme={null}
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;
```

<h3 id="sdkassistantmessage">
  `SDKAssistantMessage`
</h3>

Mensaje de respuesta del asistente.

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

El campo `message` es un [`BetaMessage`](https://platform.claude.com/docs/en/api/messages/create) del SDK de Anthropic. Incluye campos como `id`, `content`, `model`, `stop_reason` y `usage`.

`SDKAssistantMessageError` es uno de: `'authentication_failed'`, `'oauth_org_not_allowed'`, `'account_on_hold'`, `'billing_error'`, `'rate_limit'`, `'overloaded'`, `'invalid_request'`, `'model_not_found'`, `'server_error'`, `'max_output_tokens'`, `'cloud_credential_error'` o `'unknown'`. Cuatro de estos valores significan más de lo que dicen sus nombres:

* `'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](/docs/es/errors#your-account-is-on-hold)
* `'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](/docs/es/errors#could-not-load-aws-or-google-cloud-credentials). Requiere TypeScript Agent SDK v0.3.267 o posterior, que incluye Claude Code v2.1.267

`aborted` es `true` cuando una interrupción o cancelación truncó el mensaje del asistente antes de que el stream se completara: el mensaje no tiene `stop_reason` y el contenido puede terminar a mitad de una palabra. El campo está ausente en los mensajes que se completaron normalmente. Requiere Agent SDK v0.3.214 o posterior.

Claude Code establece `user_message_uuid` y `user_message_uuids` en el primer mensaje del asistente del turno, bajo las condiciones descritas en [`user_message_uuid`](#user_message_uuid). Cuando Claude Code vuelve a ejecutar un turno que un reinicio interrumpió, los mensajes del asistente de la nueva ejecución que llevan esos campos también llevan [`resume_reason`](#resume_reason).

`timestamp` es la hora ISO 8601 en que el contenido del mensaje terminó de generarse en el proceso que lo produjo. El valor proviene del reloj de esa máquina, así que úsalo solo para mostrarlo y no ordenes los mensajes según él. Un turno de API puede producir varios mensajes del asistente que comparten un `message.id`, cada uno con su propio `timestamp`. Cuando el campo está ausente, recurre a la hora en que recibiste el mensaje.

`context_usage` es una copia estructurada del informe de `/context`, con el tipo [`SDKContextUsage`](#sdkcontextusage), y requiere Agent SDK v0.3.232 o posterior. Cuando envías `/context` como prompt, Claude Code entrega el informe como un mensaje del asistente cuyo `message.content` contiene la tabla en markdown, y adjunta `context_usage` a ese mismo mensaje. Claude Code no establece el campo en ningún otro mensaje del asistente, y las versiones anteriores entregan la tabla de `/context` sin él, así que lee el desglose del campo cuando esté presente y recurre al texto en markdown cuando no lo esté.

<h3 id="sdkusermessage">
  `SDKUserMessage`
</h3>

Mensaje de entrada del usuario.

```typescript theme={null}
type SDKUserMessage = {
  type: "user";
  uuid?: UUID;
  session_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[];
};
```

Establece `pasted_content` para enviar contenido que el usuario pegó en tu interfaz de prompt en lugar de escribirlo, una entrada por pegado, cada una como una cadena o una matriz de bloques de contenido. Claude Code añade el texto de cada entrada después del texto escrito, en orden, y puede envolver cada pegado en etiquetas `<pasted_content>`. Los bloques que no son de texto se ignoran, así que envía imágenes y documentos en `message.content`. Requiere Agent SDK v0.3.277 o posterior.

Establece `inline_pastes` para indicarle a Claude Code qué partes de `message.content` pegó el usuario en lugar de escribirlas, una cadena por cada pegado. El texto del prompt permanece donde el usuario lo puso. Claude Code puede envolver cada pegado listado en etiquetas `<pasted_content>` en su lugar, para que Claude pueda distinguir el material pegado de las propias palabras del usuario. Solo se envuelven los pegados del último bloque de texto del prompt. Requiere TypeScript Agent SDK v0.3.280 o posterior.

Establece `shouldQuery`, `client_composed` o `priority` para cambiar cómo Claude Code maneja un mensaje que envías:

* `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`](/docs/es/mcp#use-mcp-resources), y no ejecuta como comando el texto que empieza con `/`. Mientras la opción [`verbatimPrompts`](#options) 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" }`](#sdkmessageorigin): 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.

Este mensaje, enviado mientras un turno está en curso, le pide a Claude que cambie de rumbo sin perder un comando de shell que todavía se está ejecutando:

```typescript theme={null}
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" },
};
```

En un mensaje que lleva un bloque `tool_result`, `tool_use_result` es el objeto de salida estructurada de la herramienta y no el texto enviado al modelo. Su forma depende de la herramienta nombrada por el bloque `tool_use` correspondiente, por lo que el campo tiene el tipo `unknown`; las formas integradas se enumeran en [Tipos de salida de herramientas](#tool-output-types). Estos resultados requieren un manejo más allá de su forma listada:

* La herramienta `Agent`: `tool_use_result` es [`AgentOutput`](#agent-2). 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](/docs/es/permission-modes#eliminate-prompts-with-auto-mode) 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](/docs/es/sub-agents#fork-the-current-conversation), 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`](#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`](#calltoolresult): `tool_use_result` es un objeto cuyo miembro `structuredContent` contiene lo que envió el servidor y cuyo miembro `content` contiene el valor [`McpOutput`](#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 Claude recibe no cambia. Las herramientas de [servidores SDK en proceso](/docs/es/agent-sdk/custom-tools) y las herramientas cuya entrada en `tools/list` declara un [recurso `_meta.ui` de MCP Apps](#mcpserverstatus) están exentas y entregan el objeto completo. Claude Code v2.1.287 o posterior aplica este límite.

<h3 id="sdkusermessagereplay">
  `SDKUserMessageReplay`
</h3>

Mensaje de usuario reproducido con UUID obligatorio.

```typescript theme={null}
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;
};
```

Un turno de usuario inyectado desde fuera de la sesión, es decir, uno cuyo tipo de [`origin`](#sdkmessageorigin) es `peer` o `channel`, llega al stream como una reproducción, tanto si se entregó durante un turno activo como si inició un nuevo turno mientras la sesión estaba inactiva. Antes de v2.1.207, un turno inyectado que se entregaba mientras la sesión estaba inactiva no producía ningún mensaje en el stream y solo aparecía cuando volvías a leer la transcripción.

<h3 id="sdkresultmessage">
  `SDKResultMessage`
</h3>

Mensaje de resultado final.

```typescript theme={null}
type SDKResultMessage =
  | {
      type: "result";
      subtype: "success";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      api_error_status?: number | null;
      num_turns: number;
      result: string;
      stop_reason: string | null;
      ttft_ms?: number;
      ttft_stream_ms?: number;
      user_message_uuid?: string;
      user_message_uuids?: string[];
      resume_reason?: string;
      local_command?: string;
      request_sent_wall_ms?: number;
      first_content_frame_ms?: number;
      first_stream_post_ms?: number;
      first_stream_post_ack_ms?: number;
      first_stream_post_queue_wait_ms?: number;
      first_stream_post_queued_behind?: "durable_post" | "ephemeral_post" | "retry_backoff" | "hold" | "none";
      first_stream_post_wall_ms?: number;
      first_text_post_ms?: number;
      first_text_post_queue_wait_ms?: number;
      first_text_post_queued_behind?: "durable_post" | "ephemeral_post" | "retry_backoff" | "hold" | "none";
      first_text_post_wall_ms?: number;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      queued_turn_count?: number;
      structured_output?: unknown;
      deferred_tool_use?: { id: string; name: string; input: Record<string, unknown> };
      terminal_reason?: TerminalReason;
      result_index?: number;
      fast_mode_state?: FastModeState;
      fast_mode_disabled_reason?: FastModeDisabledReason;
      origin?: SDKMessageOrigin;
    }
  | {
      type: "result";
      subtype:
        | "error_max_turns"
        | "error_during_execution"
        | "error_max_budget_usd"
        | "error_max_structured_output_retries";
      uuid: UUID;
      session_id: string;
      duration_ms: number;
      duration_api_ms: number;
      is_error: boolean;
      num_turns: number;
      stop_reason: string | null;
      total_cost_usd: number;
      usage: NonNullableUsage;
      modelUsage: { [modelName: string]: ModelUsage };
      permission_denials: SDKPermissionDenial[];
      queued_turn_count?: number;
      errors: string[];
      startup_failure_reason?: SDKStartupFailureReason;
      user_message_uuid?: string;
      user_message_uuids?: string[];
      resume_reason?: string;
      terminal_reason?: TerminalReason;
      result_index?: number;
      fast_mode_state?: FastModeState;
      fast_mode_disabled_reason?: FastModeDisabledReason;
      origin?: SDKMessageOrigin;
    };
```

Varios campos del resultado llevan detalles de diagnóstico más allá de `subtype`:

* `api_error_status`: el código de estado HTTP del error de API que terminó la conversación. Ausente o `null` cuando el turno terminó sin un error de API.
* `ttft_ms`: tiempo hasta el primer token en milisegundos, medido cuando llega el primer mensaje completo del asistente. Presente solo en la rama de éxito.
* `ttft_stream_ms`: tiempo en milisegundos hasta el primer evento de streaming `message_start`, cuando se abre el stream de respuesta. Es menor que `ttft_ms`; la diferencia entre ambos es el tiempo dedicado a transmitir en streaming el primer mensaje. Presente solo en la rama de éxito.
* `user_message_uuid`: el `uuid` del mensaje que enviaste y que este turno respondió. Consulta [`user_message_uuid`](#user_message_uuid) para saber qué resultados lo llevan.
* `user_message_uuids`: los `uuid` de cada mensaje que enviaste y que Claude Code respondió en este turno. Consulta [`user_message_uuids`](#user_message_uuids).
* `resume_reason`: por qué Claude Code volvió a ejecutar este turno después de que un reinicio lo interrumpiera. Presente en ambas ramas, y solo en esa nueva ejecución. Consulta [`resume_reason`](#resume_reason).
* `local_command`: el nombre del comando que despachó el turno, en el resultado de éxito de un turno que un comando completó sin entrar en el bucle del agente, como `/compact`. El nombre se convierte a letras minúsculas y guiones bajos, así que `/reload-plugins` reporta `reload_plugins`. Un comando que proporciona un servidor MCP, y el `/mcp` integrado, reportan `mcp`. Un comando que definiste tú mismo reporta `custom`. Los argumentos nunca se incluyen. Ausente en todo turno que entró en el bucle del agente y en los envíos que no ejecutaron ningún comando. Requiere Agent SDK v0.3.268 o posterior.
* `request_sent_wall_ms`: milisegundos de época en los que Claude Code despachó la solicitud de API, para cruzarlos con marcas de tiempo del lado del servidor. Presente solo junto con [`user_message_uuid`](#user_message_uuid), en un resultado de éxito con `is_error` en false cuyo turno envió una solicitud de API.
* `first_content_frame_ms`: tiempo en milisegundos hasta el primer evento de streaming `content_block_start` o `content_block_delta`, contando los bloques de pensamiento como contenido. Presente solo en la rama de éxito, cuando `is_error` es false. Requiere Agent SDK v0.3.260 o posterior.
* `first_stream_post_ms`, `first_stream_post_ack_ms`, `first_stream_post_wall_ms`: tiempos de la carga del primer evento de streaming del turno. Claude Code los registra solo en las sesiones que transmite en streaming a claude.ai, como las [sesiones en la nube](/docs/es/claude-code-on-the-web), y los resultados que produce `query()` no los llevan. Requiere Agent SDK v0.3.260 o posterior.
* `usage`: solo el bucle del agente principal. Excluye las llamadas de subagentes y de modelos auxiliares, y es por turno en las sesiones con entrada en streaming. Prefiere `modelUsage` para la contabilidad de tokens y costos.
* `modelUsage`: totales por modelo de cada llamada al modelo realizada a través del pipeline de consultas durante esta llamada a `query()`, incluidos el bucle principal, los subagentes y las llamadas internas como la compactación y los agentes de Workflow. Se excluyen las llamadas auxiliares fuera de ese pipeline, como el clasificador de permisos y las solicitudes de conteo de tokens. Una llamada que reanuda una sesión también cuenta los [totales por modelo restaurados de las llamadas anteriores de la sesión](/docs/es/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). En las sesiones con entrada en streaming, los totales son acumulativos entre turnos, así que lee el resultado más reciente en lugar de sumar entre resultados. Consulta [Rastrear costos en modo de entrada en streaming](/docs/es/agent-sdk/cost-tracking#track-costs-in-streaming-input-mode) para los reinicios y [Recuperar totales después de un fallo de la sesión](/docs/es/agent-sdk/cost-tracking#recover-totals-after-a-session-crash) para los resultados puestos a cero.
* `total_cost_usd`: costo estimado acumulativo en USD, que cubre las mismas llamadas que `modelUsage` y se reinicia en los mismos puntos. Una llamada que reanuda una sesión también cuenta los [totales restaurados de las llamadas anteriores de la sesión](/docs/es/agent-sdk/cost-tracking#accumulate-costs-across-multiple-calls). Es una estimación, no un estado de facturación. Consulta [Rastrear costo y uso](/docs/es/agent-sdk/cost-tracking) para conocer las salvedades sobre su precisión.
* `queued_turn_count`: el número de mensajes que enviaste con `origin: { kind: "human" }` que aún están esperando cuando Claude Code produjo el resultado. Consulta [`queued_turn_count`](#queued_turn_count) para saber qué te indican `0` y un campo ausente.
* `result_index`: la posición de este resultado en el orden de entrega de la ejecución, contando desde 0 entre todos los resultados que escribe el proceso. Presente en ambas ramas. Un resultado cuya escritura falla igualmente consume su número, así que un hueco en la secuencia significa que se perdió un resultado. Requiere Agent SDK v0.3.268 o posterior.
* `startup_failure_reason`: por qué Claude Code se negó a iniciar, en el resultado `error_during_execution` que escribe antes de salir ante un fallo de inicio conocido. Consulta [`startup_failure_reason`](#startup_failure_reason) para ver los valores y qué fallos lo llevan. Requiere Agent SDK v0.3.274 o posterior.
* `terminal_reason`: por qué terminó el bucle. Uno de `"completed"`, `"max_turns"`, `"tool_deferred"`, `"aborted_streaming"`, `"aborted_tools"`, `"hook_stopped"`, `"stop_hook_prevented"`, `"background_requested"`, `"blocking_limit"`, `"rapid_refill_breaker"`, `"prompt_too_long"`, `"image_error"`, `"model_error"`, `"api_error"`, `"malformed_tool_use_exhausted"`, `"budget_exhausted"`, `"structured_output_retry_exhausted"`, `"tool_deferred_unavailable"` o `"turn_setup_failed"`.
* `fast_mode_state`: uno de `"on"`, `"off"` o `"cooldown"`.
* `fast_mode_disabled_reason`: por qué el [modo rápido](/docs/es/fast-mode) no está disponible en este momento. Ausente cuando nada bloquea el modo rápido, aunque una solicitud igualmente puede ejecutarse a velocidad estándar. Durante el período de enfriamiento posterior a un rate limit del modo rápido, Claude Code reporta `fast_mode_state: "cooldown"` sin código de razón y vuelve a habilitar el modo rápido cuando expira el enfriamiento. Requiere Claude Code v2.1.219 o posterior.

Usa el código de razón para explicar en tu propia interfaz por qué el modo rápido está desactivado, en lugar de volver a deducir la disponibilidad. Cada código nombra la verificación que bloqueó el modo rápido:

| Código de razón | Significado |
| - | - |
| `free` | La cuenta no tiene la suscripción de pago ni los créditos de uso que requiere el modo rápido |
| `preference` | La organización ha deshabilitado el modo rápido |
| `extra_usage_disabled` | Los créditos de uso están desactivados para la cuenta |
| `network_error` | La [verificación de disponibilidad](/docs/es/fast-mode#use-fast-mode-behind-proxies-and-llm-gateways) no pudo conectarse con `api.anthropic.com` |
| `unknown` | Claude Code no pudo determinar la disponibilidad |
| `not_first_party` | La sesión usa un proveedor distinto de la API de Anthropic |
| `disabled_by_env` | [`CLAUDE_CODE_DISABLE_FAST_MODE`](/docs/es/env-vars) está establecida |
| `model_not_allowed` | El modelo Opus del modo rápido no está en la lista de permitidos [`availableModels`](/docs/es/model-config#restrict-model-selection) de la organización |
| `sdk_opt_in_required` | La sesión no ha optado por el modo rápido: pasa `fastMode: true` en la opción [`settings`](#options) o a través de [`applyFlagSettings()`](#applyflagsettings) |
| `pending` | La verificación de disponibilidad aún no ha terminado |

El mismo par de campos aparece en [`SDKSystemMessage`](#sdksystemmessage) y en [`SDKControlInitializeResponse`](#sdkcontrolinitializeresponse), para que puedas leer el estado del modo rápido antes del primer turno.

El campo `origin` reenvía el [`SDKMessageOrigin`](#sdkmessageorigin) del mensaje del usuario que activó este resultado. Cuando el SDK inyecta un turno de seguimiento sintético, por ejemplo para una tarea en segundo plano terminada, el `SDKResultMessage` resultante lleva `origin: { kind: "task-notification" }`. Las rutinas cuyo disparador se activó y los mensajes verificados por el servidor provenientes de tus otras sesiones también llegan con este tipo, cada uno con el `subkind` descrito en [Subtipos de notificación de tarea](#task-notification-subkinds). Verifica `kind` para distinguir los resultados que responden a tu prompt de los seguimientos inyectados antes de enrutarlos o suprimirlos. Si tu aplicación [declara ejecuciones programadas](#declare-a-scheduled-run), sus resultados también llevan `kind: "task-notification"`, así que no suprimas basándote solo en `kind`.

Cuando varias finalizaciones de tareas en segundo plano se encolan juntas, Claude Code puede responderlas en un solo turno en lugar de un turno por cada una. Cada finalización sigue produciendo su propio resultado con este origen. Todas las finalizaciones que Claude Code responde juntas, excepto la última, producen resultados vacíos con `num_turns: 0`, en orden, y el resultado de la última lleva el turno que las responde a todas.

El campo está ausente en los resultados emitidos antes de cualquier turno del usuario, como los errores de inicio.

Cuando un hook `PreToolUse` devuelve `permissionDecision: "defer"`, el resultado tiene `stop_reason: "tool_deferred"` y `deferred_tool_use` lleva el `id`, el `name` y el `input` de la herramienta pendiente. Lee este campo para mostrar la solicitud en tu propia interfaz y luego reanuda con el mismo `session_id` para continuar. Consulta [Diferir una llamada a herramienta para más tarde](/docs/es/hooks#defer-a-tool-call-for-later) para ver el recorrido completo.

<h4 id="user_message_uuid">
  `user_message_uuid`
</h4>

El `uuid` del [`SDKUserMessage`](#sdkusermessage) al que responde el turno, devuelto como eco para que puedas asociar la respuesta de Claude Code con el mensaje que enviaste. Claude Code devuelve un `uuid` solo si estableciste uno en el mensaje. El campo es opcional en `SDKUserMessage`, y un prompt de cadena pasado a `query()` no lleva ninguno.

A cuál de tus mensajes responde un turno depende de cómo comenzó el turno:

* **Un mensaje normal que enviaste**, es decir, uno sin `isSynthetic: true`: el turno responde a ese mensaje durante toda su ejecución. Cuando envías varios mensajes en poco tiempo, Claude Code puede fusionarlos en un solo turno, y el campo entonces lleva solo el `uuid` del último mensaje. Para asociar la respuesta con cualquiera de los mensajes fusionados, usa [`user_message_uuids`](#user_message_uuids).
* **Un mensaje que enviaste con `isSynthetic: true`**: el turno responde a ese mensaje al principio. Si Claude Code recoge un mensaje normal tuyo entre llamadas a herramientas, el turno responde al mensaje recogido a partir de ese momento. Devolver el `uuid` de un mensaje sintético requiere Agent SDK v0.3.265 o posterior; las versiones anteriores no devuelven nada en los turnos sintéticos.
* **El prompt que Claude Code genera para volver a ejecutar un turno interrumpido con [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/es/env-vars)**: cuando el último prompt del turno interrumpido es un mensaje normal que enviaste, ya sea que abriera el turno o que Claude Code lo recogiera durante el turno, la nueva ejecución responde a ese mensaje al principio. [`resume_reason`](#resume_reason) distingue los frames de la nueva ejecución de los del intento interrumpido. Cuando el último prompt no es un mensaje normal tuyo, la nueva ejecución no responde a ningún mensaje tuyo al principio. Si Claude Code recoge un mensaje normal tuyo entre llamadas a herramientas, el turno responde al mensaje recogido a partir de ese momento. Devolver el prompt del turno interrumpido requiere Agent SDK v0.3.268 o posterior.
* **Cualquier otro prompt que Claude Code haya generado por sí mismo**: el turno no responde a ningún mensaje tuyo al principio y sus frames no llevan eco. Si Claude Code recoge un mensaje normal tuyo entre llamadas a herramientas, el turno responde a ese mensaje a partir de ese momento. El eco de la recogida requiere Agent SDK v0.3.265 o posterior; las versiones anteriores no devuelven nada en estos turnos.

Claude Code devuelve el `uuid` del mensaje respondido en tres tipos de frame:

* **El resultado**: todo resultado de un turno que respondió a un mensaje que enviaste. Todos esos resultados lo llevan en Agent SDK v0.3.265 o posterior. Antes de v0.3.265, el resultado de éxito de un turno iniciado por un mensaje normal no lo llevaba cuando el turno no enviaba ninguna solicitud de API o terminaba con una llamada a herramienta diferida. Antes de v0.3.246, los resultados de error tampoco lo llevaban, y antes de v0.3.216 ningún resultado lo llevaba.
* **La primera respuesta del turno**: el primer [mensaje del asistente](#sdkassistantmessage) y, con `includePartialMessages`, también el primer [evento de streaming](#sdkpartialassistantmessage) cuyo `event.type` no es `ping`, para que puedas vincular la respuesta antes de que llegue el resultado. El eco en la primera respuesta requiere Agent SDK v0.3.246 o posterior. Antes de v0.3.269, con `includePartialMessages`, Claude Code lo establecía solo en ese primer evento de streaming, o en el primer mensaje del asistente cuando el turno no transmitía nada en streaming. Cuando el mensaje al que responde el turno cambia a mitad del turno, la primera respuesta después del cambio también lleva el campo, en Agent SDK v0.3.265 o posterior; las versiones anteriores lo establecen en un solo frame de respuesta por turno.
* **Cada frame [`thinking_tokens`](#sdkthinkingtokensmessage) del turno**: para que puedas atribuir el progreso del pensamiento al mensaje que enviaste sin esperar la primera respuesta del turno. Requiere Agent SDK v0.3.260 o posterior.

Claude Code omite el campo en estos casos:

* Frames de respuesta distintos de esas primeras respuestas
* Frames de subagentes
* Turnos que no responden a ningún mensaje tuyo, o que responden a un mensaje que enviaste sin `uuid`
* Resultados que no responden a ningún mensaje que enviaste, como el resultado puesto a cero después de que falla un proceso worker

<h4 id="user_message_uuids">
  `user_message_uuids`
</h4>

Los `uuid` de cada mensaje que enviaste y que Claude Code respondió en este turno. Cuando envías varios mensajes en poco tiempo, Claude Code puede fusionarlos en un solo turno, y `user_message_uuid` entonces nombra solo el último de ellos. Para asociar la respuesta con cualquiera de los mensajes fusionados, busca el `uuid` de ese mensaje en cualquier posición de esta lista. Requiere Agent SDK v0.3.259 o posterior.

Claude Code establece la lista junto con `user_message_uuid` en cada frame de respuesta que lleva ese campo y en el resultado. Para ver el conjunto completo de frames del turno que devuelven el `uuid` del mensaje respondido, y la versión que requiere cada uno, consulta [`user_message_uuid`](#user_message_uuid). La lista siempre contiene `user_message_uuid` y tiene como máximo 64 entradas.

Cuando Claude Code recoge un mensaje normal que enviaste mientras se ejecutaba un turno, añade el `uuid` de ese mensaje a la lista del resultado.

Cuando una primera respuesta o un resultado lleva `user_message_uuid` sin la lista, proviene de una versión anterior de Claude Code, así que recurre al campo individual.

<h4 id="resume_reason">
  `resume_reason`
</h4>

Por qué Claude Code volvió a ejecutar este turno después de un reinicio. Claude Code establece este campo en un turno que volvió a ejecutar con [`CLAUDE_CODE_RESUME_INTERRUPTED_TURN`](/docs/es/env-vars), para que puedas distinguir la respuesta y el resultado de la nueva ejecución de los del intento interrumpido. Requiere Agent SDK v0.3.268 o posterior.

Claude Code establece el campo en dos tipos de frame:

* **El resultado de la nueva ejecución**: tanto en la rama de éxito como en la de error, lleve o no el resultado `user_message_uuid`.
* **Los frames de respuesta de la nueva ejecución**: aquellos que llevan [`user_message_uuid`](#user_message_uuid).

El valor es un token breve en minúsculas que indica por qué se volvió a ejecutar el turno, como `interrupted_turn`. El campo está ausente en todos los demás turnos.

<h4 id="queued_turn_count">
  `queued_turn_count`
</h4>

El número de mensajes que enviaste con [`origin: { kind: "human" }`](#sdkmessageorigin) que aún están esperando en la cola de comandos cuando Claude Code produjo el resultado. Requiere Agent SDK v0.3.242 o posterior.

Qué te indican `0` y un campo ausente:

* **`0`**: Claude Code no cuenta los mensajes que enviaste sin ese `origin`, ni cuenta las notificaciones de tareas, así que igualmente puede seguir un turno.
* **Ausente**: el resultado final que Claude Code emite después de un fallo o de un error fatal de inicio omite el campo, y [puede llevar totales puestos a cero](/docs/es/agent-sdk/cost-tracking#recover-totals-after-a-session-crash).

<h4 id="startup_failure_reason">
  `startup_failure_reason`
</h4>

Por qué Claude Code se negó a iniciar, para que tu aplicación pueda ofrecer la solución en lugar de un reintento. Claude Code lo establece en el resultado `error_during_execution` que escribe antes de salir ante un fallo de inicio conocido. Ese resultado lleva totales puestos a cero, y su matriz `errors` lleva el mismo texto que stderr. El campo está ausente en todos los demás resultados. Requiere Agent SDK v0.3.274 o posterior.

Establece `CLAUDE_CODE_STARTUP_FAILURE_RESULTS` en `1` en [`env`](#options) para recibir este resultado con cualquier valor de `SDKStartupFailureReason`. Sin esa variable, Claude Code escribe el resultado solo para estos fallos, y el resto termina con salida en stderr, un código de salida distinto de cero y ningún mensaje de resultado:

* Una reanudación que Claude Code detiene porque [no puede devolver la sesión a su worktree](/docs/es/worktrees#the-session-resumes-outside-its-worktree), con `worktree_unverified` o `worktree_resume_refused`. Esa sección indica qué error lleva cada valor.
* Un [`continue`](#options) rechazado de una conversación que retiene una sesión en segundo plano, con `session_held_by_background`. Para un [`resume`](#options) rechazado de esa conversación, Claude Code escribe el resultado solo cuando la variable está establecida.

```typescript theme={null}
type SDKStartupFailureReason =
  | "org_pin_api_key_conflict"
  | "provider_not_allowed"
  | "org_verify_failed"
  | "org_pin_mismatch"
  | "managed_settings_invalid"
  | "remote_settings_required_unavailable"
  | "gateway_signin_required"
  | "gateway_access_denied"
  | "proxy_invalid"
  | "temp_dir_unusable"
  | "cwd_unavailable"
  | "shell_tool_missing"
  | "session_held_by_background"
  | "worktree_resume_refused"
  | "worktree_unverified"
  | "cli_version_too_old"
  | "bypass_root";
```

Cada valor nombra un rechazo:

| Valor | Qué detuvo la sesión |
| :- | :- |
| `org_pin_api_key_conflict` | La configuración administrada [exige un inicio de sesión de primera parte o mediante el gateway en la nube](/docs/es/authentication#restrict-login-to-your-organization), y en su lugar hay configurada una clave de API de Anthropic, un token de autenticación o un `apiKeyHelper` |
| `provider_not_allowed` | La configuración administrada [enumera los proveedores de API que esta máquina puede usar](/docs/es/settings-reference#allowedproviders), y la sesión está configurada para un proveedor que no está en la lista, o para un endpoint que la configuración no fija. Requiere Claude Code v2.1.285 o posterior |
| `org_verify_failed` | No se pudo verificar la organización del inicio de sesión contra el pin, por ejemplo debido a un fallo de red o a un token revocado |
| `org_pin_mismatch` | El inicio de sesión pertenece a una organización que el pin no permite |
| `managed_settings_invalid` | No se pudo leer la configuración de políticas administrada, el pin no nombra ninguna organización, o las [restricciones de modelos administradas](/docs/es/errors#managed-settings-block-the-default-model) no dejan ningún modelo permitido para la opción Predeterminado |
| `remote_settings_required_unavailable` | No se pudo cargar la configuración administrada que exige la organización |
| `gateway_signin_required` | El [gateway en la nube](/docs/es/claude-apps-gateway) cerró este inicio de sesión |
| `gateway_access_denied` | La solicitud de configuración administrada al gateway en la nube devolvió un 403, que cubre la [tabla de solución de problemas](/docs/es/claude-apps-gateway-deploy#troubleshooting) del gateway |
| `proxy_invalid` | Un ajuste de proxy no es una URL completa |
| `temp_dir_unusable` | El directorio temporal por usuario no es seguro o no se pudo crear |
| `cwd_unavailable` | El directorio de trabajo se eliminó, se movió o no se puede leer |
| `shell_tool_missing` | En Windows, no hay ninguna herramienta de shell disponible: falta Git Bash, y PowerShell falta o está desactivado con `CLAUDE_CODE_USE_POWERSHELL_TOOL` |
| `session_held_by_background` | La conversación que se quiere reanudar o continuar se está ejecutando como una [sesión en segundo plano](/docs/es/agent-view) |
| `worktree_resume_refused` | El worktree de la sesión no superó sus verificaciones de seguridad, o la reanudación se lanzó desde dentro de él. `errors` indica si ejecutar de nuevo la misma reanudación continúa sin el worktree |
| `worktree_unverified` | No se pudo verificar el worktree de la sesión en este momento, y reintentar puede funcionar |
| `cli_version_too_old` | Esta versión de Claude Code está por debajo del mínimo que exige Anthropic |
| `bypass_root` | Se solicitó el modo de permisos bypass mientras se ejecutaba como root |

<h3 id="sdksystemmessage">
  `SDKSystemMessage`
</h3>

Mensaje de inicialización del sistema.

```typescript theme={null}
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;
    source?: string;
  }[];
  model: string;
  permissionMode: PermissionMode;
  slash_commands: string[];
  terminal_slash_commands?: string[];
  output_style: string;
  skills: string[];
  plugins: { name: string; path: string }[];
  plugin_errors?: {
    plugin: string;
    type: string;
    message: string;
    path?: string;
  }[];
  fast_mode_state?: FastModeState;
  fast_mode_disabled_reason?: FastModeDisabledReason;
  effort?: "low" | "medium" | "high" | "xhigh" | "max" | null;
  capabilities?: string[];
};
```

`fast_mode_state` reporta el estado del [modo rápido](/docs/es/fast-mode) de la sesión. Cuando algo bloquea el modo rápido, `fast_mode_disabled_reason` nombra la verificación que lo bloqueó; el campo requiere Claude Code v2.1.219 o posterior. Para ver los códigos de razón y sus significados, consulta [`fast_mode_disabled_reason`](#sdkresultmessage) en el mensaje de resultado.

`terminal_slash_commands` nombra las entradas de `slash_commands` cuya interfaz está vinculada a la terminal local, como `exit`. Puedes enviarlas como cualquier otra entrada de `slash_commands`; el campo existe para que un cliente remoto o móvil pueda ocultarlas de sus menús de comandos. El campo está presente solo cuando no está vacío, y requiere Agent SDK v0.3.229 o posterior.

* `source` en cada entrada de `mcp_servers`: de dónde proviene la definición del servidor, con los mismos valores que el `source` de [`McpServerStatus`](#mcpserverstatus). Requiere Agent SDK v0.3.274 o posterior.
* `effort`: el [nivel de esfuerzo](/docs/es/model-config#adjust-effort-level) que Claude Code envía en la siguiente solicitud de la sesión, o `null` cuando no envía ninguno. Claude Code establece el campo solo en el mensaje de inicialización que envía a los clientes de [Remote Control](/docs/es/remote-control), y lo omite del mensaje de inicialización que lee tu aplicación. Requiere Agent SDK v0.3.234 o posterior.

La matriz `capabilities` nombra los comportamientos del protocolo que implementa esta CLI, para que puedas detectar funcionalidades en lugar de comparar cadenas de `claude_code_version`. Es un conjunto abierto: ignora los valores que no reconozcas y verifica la capacidad específica de cuyo comportamiento dependes. El campo requiere Claude Code v2.1.205 o posterior y está ausente en las CLI anteriores.

| Capacidad | Significado |
| - | - |
| `interrupt_receipt_v1` | [`interrupt()`](#query-object) se resuelve con un recibo [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse) que enumera los mensajes que estaban pendientes cuando llegó la interrupción |
| `interrupt_cancel_queued_v1` | La solicitud de control `interrupt` respeta `cancel_queued: true`: cancela los mensajes que el recibo enumeraría en `still_queued` y, en su lugar, los enumera en `cancelled`. Consulta [`SDKControlInterruptResponse`](#sdkcontrolinterruptresponse). Requiere Claude Code v2.1.219 o posterior |
| `sdk_mcp_manifests` | La solicitud de control `initialize` acepta `sdkMcpServerManifests`, resultados del handshake MCP capturados de tus [servidores MCP del SDK](/docs/es/agent-sdk/custom-tools) en proceso. Claude Code anuncia esta capacidad en v2.1.286 o posterior |
| `sdk_mcp_tools_list_changed` | Una notificación `tools/list_changed` de un [servidor MCP del SDK](/docs/es/agent-sdk/custom-tools) hace que Claude Code vuelva a listar las herramientas de ese servidor, para que una herramienta que el servidor añade a mitad de sesión llegue a Claude. Claude Code anuncia esta capacidad en v2.1.286 o posterior |

La matriz `plugin_errors` enumera los fallos de carga de plugins. Una entrada describe o bien un plugin que no se cargó y está ausente de `plugins`, o bien un plugin que se cargó sin una de sus partes, como su archivo de hooks. La clave se omite cuando nada falló. `SDKSystemMessage` declara `plugin_errors` en Agent SDK v0.3.283 o posterior.

Cuando un directorio o archivo comprimido de tu [opción `plugins`](#options) falla al cargarse por sí mismo, el campo `plugin` de la entrada contiene una etiqueta posicional como `inline[0]` en lugar de un nombre de plugin. Esto sucede, por ejemplo, cuando la ruta no existe o el manifiesto no es válido. Asocia esa entrada con tu opción mediante su campo `path`.

La tabla siguiente enumera los campos de cada entrada de `plugin_errors`.

| Campo | Tipo | Descripción |
| - | - | - |
| `plugin` | `string` | El ID del plugin que falló, o una etiqueta posicional como `inline[0]` cuando el propio directorio o archivo comprimido del plugin falló al cargarse |
| `type` | `string` | Categoría de error de un conjunto abierto, como `path-not-found` o `manifest-validation-error`. Trata un valor que no reconozcas como un fallo genérico |
| `message` | `string` | Texto para mostrar que describe el fallo |
| `path` | `string` | Presente solo cuando el propio directorio o archivo comprimido del plugin falló al cargarse. Su ruta absoluta; una ruta relativa de tu opción `plugins` se resuelve con respecto a la opción [`cwd`](#options) |

<h3 id="sdkpartialassistantmessage">
  `SDKPartialAssistantMessage`
</h3>

Mensaje parcial en streaming (solo cuando `includePartialMessages` es true). El campo `parent_tool_use_id` siempre es `null`: los eventos de streaming se emiten solo para la sesión principal. Para atribuir contenido a subagentes, usa los mensajes completos, que llevan `parent_tool_use_id`, o habilita [`forwardSubagentText`](#options) para recibir el texto y el pensamiento de los subagentes como mensajes completos.

```typescript theme={null}
type SDKPartialAssistantMessage = {
  type: "stream_event";
  event: BetaRawMessageStreamEvent; // From Anthropic SDK
  parent_tool_use_id: string | null;
  uuid: UUID;
  session_id: string;
  ttft_ms?: number; // Time to first token in ms, present only on message_start events
  user_message_uuid?: string;
  user_message_uuids?: string[];
  resume_reason?: string;
};
```

Claude Code establece `user_message_uuid` y `user_message_uuids` en el primer evento de streaming del turno que no es ping, y de nuevo cuando cambia el mensaje al que responde el turno, bajo las condiciones descritas en [`user_message_uuid`](#user_message_uuid). Cuando Claude Code vuelve a ejecutar un turno que un reinicio interrumpió, los eventos de streaming de la nueva ejecución que llevan esos campos también llevan [`resume_reason`](#resume_reason).

<h3 id="sdkcompactboundarymessage">
  `SDKCompactBoundaryMessage`
</h3>

Mensaje que indica un límite de compactación de la conversación.

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

<h3 id="sdkinformationalmessage">
  `SDKInformationalMessage`
</h3>

Banner de texto genérico emitido por el bucle. Lleva advertencias, avisos y otras líneas de estado que no son errores y que genera Claude Code, así como retroalimentación de hooks, como el motivo de bloqueo de un hook `UserPromptSubmit`.

En Claude Code v2.1.227 o posterior, el [`systemMessage`](/docs/es/hooks#json-output) de un hook puede llegar como este mensaje, con cada línea precedida por el nombre del hook, como `PostToolUse:Bash says:`. La [sección de cada evento](/docs/es/hooks#hook-events) en la página de hooks indica cómo se muestra la salida.

Renderiza `content` como texto sin formato con el `level` indicado.

```typescript theme={null}
type SDKInformationalMessage = {
  type: "system";
  subtype: "informational";
  content: string;
  level: "info" | "notice" | "suggestion" | "warning";
  tool_use_id?: string;
  prevent_continuation?: boolean;
  uuid: UUID;
  session_id: string;
};
```

<h3 id="sdkworkershuttingdownmessage">
  `SDKWorkerShuttingDownMessage`
</h3>

Se emite cuando el worker se cierra de forma ordenada, para que los clientes remotos puedan mostrar por qué salió el worker en lugar de esperar a que se agote el tiempo de espera del heartbeat. `reason` es una cadena breve en snake\_case establecida por la CLI host, como `"host_exit"` o `"remote_control_disabled"`. Actúa en consecuencia solo cuando estés recibiendo el streaming en vivo. Una sesión reanudada reproduce instancias anteriores de este mensaje, así que ignóralas en ese caso.

```typescript theme={null}
type SDKWorkerShuttingDownMessage = {
  type: "system";
  subtype: "worker_shutting_down";
  reason: string;
  uuid: UUID;
  session_id: string;
};
```

<h3 id="sdkplugininstallmessage">
  `SDKPluginInstallMessage`
</h3>

Evento de progreso de la instalación de plugins. Se emite cuando [`CLAUDE_CODE_SYNC_PLUGIN_INSTALL`](/docs/es/env-vars) está establecida, para que tu aplicación del Agent SDK pueda rastrear la instalación de plugins del marketplace antes del primer turno. Los estados `started` y `completed` delimitan la instalación completa. Los estados `installed` y `failed` reportan marketplaces individuales e incluyen `name`.

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

<h3 id="sdkpermissiondeniedmessage">
  `SDKPermissionDeniedMessage`
</h3>

Evento de streaming que se emite cuando el sistema de permisos deniega una llamada a herramienta sin una solicitud de permiso interactiva. Úsalo para mostrar la denegación en tu interfaz en el momento en que ocurre, en lugar de solo observar el resultado de herramienta con `is_error` que viene después. Qué denegaciones reporta depende de cómo maneja la ejecución las solicitudes de permiso:

* **Con un callback [`canUseTool`](#canusetool)** y el valor predeterminado [`permissionPrompts: 'host'`](#options): las solicitudes de permiso van a tu callback, y este evento reporta las denegaciones que Claude Code decide por su cuenta sin llamarlo.
* **Sin ninguno de los dos**: una ejecución `-p` simple, o un `query()` que no establece `canUseTool` ni `permissionPromptToolName`, deniega cualquier llamada a herramienta que habría pedido permiso, a menos que un [hook `PermissionRequest`](/docs/es/hooks-guide#limitations) la permita, y este evento informa esas denegaciones así como las que Claude Code decide por sí mismo. Antes de v2.1.223, Claude Code no emitía este evento en ejecuciones sin callback.
* **Con una herramienta de solicitud de permisos MCP**, establecida con `permissionPromptToolName` o con el flag [`--permission-prompt-tool`](/docs/es/cli-reference#cli-flags), y el valor predeterminado `permissionPrompts: 'host'`: Claude Code no emite este evento en absoluto, ni siquiera para las denegaciones por reglas que decide por su cuenta.
* **Con [`permissionPrompts: 'none'`](#options)**: Claude Code deniega las llamadas que habrían requerido una solicitud de permiso, incluso cuando también está establecido `canUseTool` o una herramienta de solicitud de permisos MCP, y este evento reporta esas denegaciones además de las que Claude Code decide por su cuenta. Requiere Claude Code v2.1.259 o posterior.

En cualquier configuración, este evento omite toda denegación decidida en la ruta del hook `PreToolUse`, tanto si el propio hook denegó la llamada como si una regla de denegación anuló la decisión de permitir o preguntar del hook. Además, el evento funciona con el mejor esfuerzo posible: ocasionalmente Claude Code registra una denegación sin emitir este evento, así que `permission_denials` en el [mensaje de resultado](#sdkresultmessage) es el registro de referencia.

```typescript theme={null}
type SDKPermissionDeniedMessage = {
  type: "system";
  subtype: "permission_denied";
  tool_name: string;
  tool_use_id: string;
  agent_id?: string;
  decision_reason_type?: string;
  decision_reason?: string;
  message: string;
  uuid: UUID;
  session_id: string;
};
```

| Campo | Tipo | Descripción |
| - | - | - |
| `tool_name` | `string` | Nombre de la herramienta denegada |
| `tool_use_id` | `string` | ID del bloque `tool_use` al que responde esta denegación |
| `agent_id` | `string` | ID del subagente cuando la llamada denegada se originó dentro de un subagente. Replica el campo de `can_use_tool` para el enrutamiento del lado del host |
| `decision_reason_type` | `string` | Discriminador del componente que decidió, como `"rule"`, `"mode"`, `"classifier"` o `"asyncAgent"` |
| `decision_reason` | `string` | Motivo legible por humanos del componente que decidió, cuando está disponible |
| `message` | `string` | Mensaje de rechazo devuelto al modelo en el `tool_result` |

<h3 id="sdkpermissiondenial">
  `SDKPermissionDenial`
</h3>

Información sobre un uso de herramienta denegado.

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

<h3 id="sdkcontextusage">
  `SDKContextUsage`
</h3>

Forma estructurada del informe de `/context`, que llega como `context_usage` en el [`SDKAssistantMessage`](#sdkassistantmessage) que entrega un resultado de `/context`. Agent SDK v0.3.232 y posteriores exportan el tipo. A diferencia de [`SDKControlGetContextUsageResponse`](#sdkcontrolgetcontextusageresponse), lleva solo los datos necesarios para renderizar el desglose de uso, sin campos de visualización como `color` y `gridRows`. Claude Code calcula el informe con solicitudes de API de conteo de tokens que no aparecen en el stream de mensajes; consulta [cómo se manejan estas solicitudes](#sdkcontrolgetcontextusageresponse).

```typescript theme={null}
type SDKContextUsage = {
  model: string;
  total_tokens: number;
  raw_max_tokens: number;
  percentage: number;
  over_limit?: {
    tokens_over: number;
    kind: "hard_limit" | "compaction_window";
  };
  categories: SDKContextUsageCategory[];
  mcp_tools: {
    name: string;
    server_name: string;
    tokens: number;
  }[];
  memory_files: {
    path: string;
    type: string;
    tokens: number;
  }[];
  agents: {
    agent_type: string;
    source: string;
    tokens: number;
  }[];
  skills?: {
    name: string;
    source: string;
    plugin_name?: string;
    tokens: number;
  }[];
};
```

La tabla enumera lo que Claude Code pone en cada campo. Los campos desde `model` hasta `over_limit` describen la sesión en su conjunto, y los campos de colección atribuyen tokens a elementos individuales.

| Campo | Tipo | Descripción |
| - | - | - |
| `model` | `string` | El modelo del bucle principal para el que Claude Code calculó el uso, no el de un subagente |
| `total_tokens` | `number` | La estimación de Claude Code de los tokens en uso. No se limita a la ventana, así que puede superar `raw_max_tokens` cuando la sesión excede el límite |
| `raw_max_tokens` | `number` | La ventana de contexto del modelo, o la [ventana de compactación automática](/docs/es/model-config#context-window-and-auto-compaction) más baja cuando se aplica una, como una que hayas establecido o el límite de 200K que Claude Code aplica a algunos modelos con una ventana de 1M de tokens. Claude Code mide `total_tokens` con respecto a esta ventana |
| `percentage` | `number` | `total_tokens` como porcentaje redondeado de `raw_max_tokens`, así que puede superar 100 cuando la sesión excede el límite |
| `over_limit` | `object` | Presente solo cuando `total_tokens` supera `raw_max_tokens`. `tokens_over` es la cantidad excedida, y `kind` indica cómo resolvió Claude Code la ventana |
| `categories` | [`SDKContextUsageCategory`](#sdkcontextusagecategory)`[]` | Una entrada por cada fila del desglose de uso por categoría |
| `mcp_tools` | `object[]` | Tokens atribuidos a cada herramienta MCP, con su nombre de protocolo, como `mcp__linear__create_issue`, y su `server_name` |
| `memory_files` | `object[]` | Tokens atribuidos a cada archivo de memoria cargado, con su `path` y una etiqueta de origen como `Project` o `User` en `type` |
| `agents` | `object[]` | Tokens atribuidos a cada definición de subagente personalizado, con un identificador de origen como `projectSettings`, `userSettings` o `plugin`. Los subagentes integrados no se enumeran |
| `skills` | `object[]` | Tokens atribuidos a cada skill de la lista de skills, con un identificador de origen y, para los skills de plugins, el nombre del plugin en `plugin_name`. Ausente cuando ningún skill aporta tokens |

`over_limit.kind` registra cómo resolvió Claude Code la ventana, no si la API acepta la siguiente solicitud:

* `hard_limit`: la ventana es lo que Claude Code cree que es el límite propio del modelo, a partir del cual la API rechaza las solicitudes
* `compaction_window`: la ventana es una ventana de la política de compactación, que puede coincidir o no con el límite del modelo

Claude Code hace evolucionar el tipo de forma aditiva, añadiendo datos nuevos como campos opcionales en lugar de reestructurar los existentes. Lee los campos que conoces e ignora los que no reconozcas.

<h3 id="sdkcontextusagecategory">
  `SDKContextUsageCategory`
</h3>

Una fila del desglose de uso por categoría de `/context`.

```typescript theme={null}
type SDKContextUsageCategory = {
  name: string;
  tokens: number;
  kind: "used" | "free" | "buffer" | "deferred";
};
```

La tabla enumera lo que Claude Code pone en cada campo de una fila.

| Campo | Tipo | Descripción |
| - | - | - |
| `name` | `string` | El nombre para mostrar de la fila tal como lo imprime `/context`, como `Messages`. Clasifica las filas por `kind`, no por el nombre |
| `tokens` | `number` | El recuento de tokens de la fila. Las filas pueden tener cero tokens |
| `kind` | `string` | Lo que representa la fila: `used`, `free`, `buffer` o `deferred` |

Cada valor de `kind` indica qué son los tokens de la fila:

* `used`: contenido que ocupa la ventana de contexto
* `free`: la ventana restante
* `buffer`: la reserva para la compactación
* `deferred`: esquemas de herramientas que Claude Code mantiene fuera de la ventana y excluye del cálculo de uso, enumerados a título informativo

<h3 id="sdkmessageorigin">
  `SDKMessageOrigin`
</h3>

Procedencia de un mensaje con rol de usuario. Aparece como `origin` en [`SDKUserMessage`](#sdkusermessage) y se reenvía al [`SDKResultMessage`](#sdkresultmessage) correspondiente para que puedas saber qué activó un turno determinado.

```typescript theme={null}
type SDKMessageOrigin =
  | { kind: "human" }
  | { kind: "channel"; server: string }
  | {
      kind: "peer";
      from: string;
      fromMode?: "bypass" | "prompting";
      name?: string;
      fromSession?: string;
      senderTaskId?: string;
      body?: string;
      verifiedPeerPid?: number;
    }
  | {
      kind: "task-notification";
      subkind?: "scheduled-trigger" | "peer-send-message";
      fireReason?: string;
    }
  | { kind: "coordinator" }
  | { kind: "auto-continuation" }
  | { kind: "unclassified" };
```

| `kind` | Significado |
| - | - |
| `human` | Entrada directa del usuario final. Si tu aplicación reenvía lo que escribió el usuario como un mensaje de usuario, establece su `origin` en `{ kind: "human" }` de forma explícita: Claude Code trata un mensaje de usuario sin `origin` como no atribuido, y las verificaciones que exigen un prompt escrito por una persona, como la [palabra clave de flujo de trabajo `ultracode`](/docs/es/workflows#ask-for-a-workflow-in-your-prompt), no lo aceptan. Antes de v2.1.210, Claude Code trataba un `origin` ausente en un mensaje de usuario como entrada humana. |
| `channel` | Mensaje que llega por un [canal](/docs/es/channels). `server` es el nombre del servidor MCP de origen. |
| `peer` | Mensaje de otro agente: un [compañero de equipo](/docs/es/agent-teams) dentro del proceso o un [par entre sesiones](/docs/es/cross-session-messaging), es decir, otra de tus sesiones de Claude Code. Consulta [Campos de origen de par](#peer-origin-fields) para ver la semántica de cada campo y el modelo de confianza. |
| `task-notification` | Turno sintético inyectado para una entrega que llega sin un prompt nuevo del usuario, como una tarea en segundo plano terminada; consulta [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) para esa rama. Un prompt que tu aplicación [declara como ejecución programada](#declare-a-scheduled-run) también lleva este tipo. El `subkind` opcional indica qué generó la notificación. Consulta [Subtipos de notificación de tarea](#task-notification-subkinds). |
| `coordinator` | Mensaje de un coordinador de equipo en un [equipo de agentes](/docs/es/agent-teams). |
| `auto-continuation` | Turno sintético inyectado cuando la sesión continúa sin una entrada nueva del usuario, como un resultado de comando que activa un prompt de seguimiento. |
| `unclassified` | Turno inyectado cuyo origen no se pudo determinar. Requiere Claude Code v2.1.223 o posterior. Cuando Claude Code recibe un [`SDKUserMessage`](#sdkusermessage) con `isSynthetic: true` y no puede clasificarlo como ningún otro `kind`, establece este tipo al llegar el mensaje y le presenta el turno al modelo como una fuente que no es el usuario, en lugar de tratarlo como entrada humana. Tu aplicación no debe establecer este valor. |

<h3 id="task-notification-subkinds">
  Subtipos de notificación de tarea
</h3>

Cuando Claude Code entrega una notificación de tarea en una sesión, establece `subkind` en el `origin` de la notificación si los servidores de Anthropic verificaron de dónde provino esa notificación. También establece `subkind` cuando tu propia aplicación [declara el mensaje como ejecución programada](#declare-a-scheduled-run), lo que requiere TypeScript Agent SDK v0.3.280 o posterior. `subkind` requiere Claude Code v2.1.213 o posterior y toma uno de dos valores:

* `scheduled-trigger`: la notificación es el prompt almacenado de una [rutina](/docs/es/routines), entregado porque se activó uno de los disparadores de la rutina: su horario, su [disparador de API](/docs/es/routines#add-an-api-trigger), su [disparador de GitHub](/docs/es/routines#add-a-github-trigger) o **Ejecutar ahora**. Un prompt que tu aplicación [declara como ejecución programada](#declare-a-scheduled-run) también lleva este valor. Claude Code se los presenta al modelo como la tarea asignada de la sesión, con un aviso distinto del [aviso que llevan las demás notificaciones de tarea](#sdktasknotificationmessage).
* `peer-send-message`: la notificación es un mensaje que otra de tus sesiones envió con la herramienta `send_message` del lado del servidor que usan las [sesiones en la nube](/docs/es/claude-code-on-the-web) para enviarse mensajes entre sí, no con la [herramienta `SendMessage` entre sesiones](/docs/es/cross-session-messaging), y los servidores de Anthropic verificaron que ambas sesiones pertenecen al mismo grupo privado de sesiones. Requiere Claude Code v2.1.224 o posterior. Una entrega de `send_message` que los servidores no verificaron de esa forma no recibe ningún subkind.

Todas las demás notificaciones de tarea no tienen `subkind`. Eso incluye la [actividad de PR](/docs/es/claude-code-on-the-web#how-claude-responds-to-pr-activity) entregada en una sesión y los eventos en segundo plano, como una tarea terminada. Los mensajes de la [herramienta `SendMessage` entre sesiones](/docs/es/cross-session-messaging) no son notificaciones de tarea en absoluto: tanto si provienen de una sesión en la misma máquina como si llegan a través de los servidores de Anthropic desde otra máquina, Claude Code les asigna `kind: "peer"` y los [campos de origen de par](#peer-origin-fields).

`fireReason` indica por qué se activó una notificación `scheduled-trigger`, como un token breve en minúsculas, por ejemplo `scheduled`, `manual`, `retry`, `catch_up` o `api`. Los servidores de Anthropic lo establecen en las entregas de una [rutina](/docs/es/routines), y tu aplicación lo establece cuando declara una ejecución programada. Está ausente cuando ninguno de los dos envió uno. Requiere TypeScript Agent SDK v0.3.280 o posterior.

<h4 id="declare-a-scheduled-run">
  Declarar una ejecución programada
</h4>

Si tu aplicación ejecuta prompts según su propio horario, declara cada ejecución para que Claude Code le presente el turno al modelo como una tarea programada en lugar de como entrada en vivo del usuario. Inicia la sesión con `CLAUDE_CODE_HOST_SCHEDULED_RUN` establecida en `1` en [`env`](#options) y luego envía el [`SDKUserMessage`](#sdkusermessage) de la ejecución con `origin: { kind: "task-notification", subkind: "scheduled-trigger", fireReason: "scheduled" }` y sin `isSynthetic`. Claude Code ignora la declaración en un proceso iniciado sin esa variable. También la ignora en un proceso cuyo entorno contiene [`CLAUDECODE`](/docs/es/env-vars) o `CLAUDE_CODE_CHILD_SESSION`. Claude Code conserva `fireReason` solo cuando el valor tiene de 1 a 32 letras minúsculas o guiones bajos. Requiere TypeScript Agent SDK v0.3.280 o posterior.

<h3 id="peer-origin-fields">
  Campos de origen de par
</h3>

Un origen `peer` identifica qué agente envió el mensaje: un [compañero de equipo](/docs/es/agent-teams) dentro del proceso que envía a `main` con `SendMessage`, o un [par entre sesiones](/docs/es/cross-session-messaging), es decir, otra de tus sesiones de Claude Code. Los pares entre sesiones requieren Claude Code v2.1.224 o posterior en macOS y Linux; consulta [disponibilidad de la mensajería entre sesiones](/docs/es/cross-session-messaging#availability) para ver el requisito en Windows nativo. Un par entre sesiones puede ejecutarse en la misma máquina, o en [otra de tus máquinas](/docs/es/cross-session-messaging#message-sessions-on-other-machines) o [en la nube](/docs/es/claude-code-on-the-web) cuando su mensaje llega a través de Remote Control. Los dos tipos de remitente rellenan los campos de forma distinta:

* `from`: el nombre del compañero de equipo, o la dirección del remitente en el caso de un par entre sesiones. En un [mensaje unidireccional entre máquinas](/docs/es/cross-session-messaging#message-sessions-on-other-machines), el remitente no tiene dirección de respuesta y `from` es `"unknown"`. El valor lo escribe el remitente; `verifiedPeerPid` es la identidad verificada.
* `fromMode`: la clase de permisos de la sesión que envía, `bypass` o `prompting`, declarada por un host que retransmite un mensaje de par entre tus sesiones, como la [aplicación de escritorio](/docs/es/desktop#work-across-sessions). Claude Code lo lee en la sesión receptora cuando aplica los [controles de mensajes entrantes](/docs/es/cross-session-messaging#control-inbound-messages). Requiere Agent SDK v0.3.234 o posterior.
* `senderTaskId`: el ID de tarea del compañero de equipo. Ausente en el caso de un par entre sesiones.
* `name`: el nombre para mostrar del remitente, normalizado por Claude Code: elimina los puntos de código Unicode de control, de formato, sustitutos y separadores de línea o de párrafo, luego recorta el resultado y lo limita a 64 puntos de código con puntos suspensivos. Requiere Claude Code v2.1.205 o posterior.
* `body`: el cuerpo decodificado del mensaje sin el envoltorio de par, idéntico byte a byte a lo que ve el modelo. Siempre presente en un mensaje de un compañero de equipo; en el caso de un par entre sesiones, presente solo cuando el turno es exactamente un envoltorio de par formado por Claude Code. Renderiza `name` y `body` en lugar de volver a analizar el texto del mensaje. Requiere Claude Code v2.1.205 o posterior.
* `fromSession`: el ID de sesión del remitente que su host puede abrir, establecido por el host del remitente para que tu interfaz pueda enlazar de vuelta a la sesión que envió el mensaje. Al igual que `from`, lo afirma el remitente: úsalo solo como destino de navegación y no lo trates como prueba de la identidad del remitente. Requiere Claude Code v2.1.216 o posterior.
* `verifiedPeerPid`: el ID del proceso que se conectó al socket de mensajería entre sesiones de esta sesión, verificado por el kernel y leído de la propia conexión, nunca del payload. Úsalo, y no `from`, para identificar al remitente: cualquier proceso del mismo usuario puede falsificar `from`. El campo está ausente cuando Claude Code no puede verificarlo, como en Windows o en entradas que no llegan por socket, así que un valor ausente significa que el remitente no está verificado. En el tráfico retransmitido identifica al relay en lugar del autor del mensaje, y los ID de proceso se reutilizan, así que trátalo como procedencia y no como un token de autenticación. Requiere Claude Code v2.1.216 o posterior.

<h2 id="hook-types">
  Tipos de Hook
</h2>

Para una guía sobre el uso de hooks con ejemplos y patrones comunes, consulta la [guía de Hooks](/docs/es/agent-sdk/hooks).

<h3 id="hookevent">
  `HookEvent`
</h3>

Eventos de hook disponibles.

```typescript theme={null}
type HookEvent =
  | "PreToolUse"
  | "PostToolUse"
  | "PostToolUseFailure"
  | "PostToolBatch"
  | "Notification"
  | "UserPromptSubmit"
  | "UserPromptExpansion"
  | "SessionStart"
  | "SessionEnd"
  | "Stop"
  | "StopFailure"
  | "SubagentStart"
  | "SubagentStop"
  | "PreCompact"
  | "PostCompact"
  | "PreModelSwitch"
  | "PostModelSwitch"
  | "PermissionRequest"
  | "PermissionDenied"
  | "Setup"
  | "TeammateIdle"
  | "TaskCreated"
  | "TaskCompleted"
  | "Elicitation"
  | "ElicitationResult"
  | "ConfigChange"
  | "DirectoryAdded"
  | "WorktreeCreate"
  | "WorktreeRemove"
  | "InstructionsLoaded"
  | "CwdChanged"
  | "FileChanged"
  | "MessageDisplay";
```

<h3 id="hookcallback">
  `HookCallback`
</h3>

Tipo de función de devolución de llamada de hook.

```typescript theme={null}
type HookCallback = (
  input: HookInput, // Unión de todos los tipos de entrada de hook
  toolUseID: string | undefined,
  options: { signal: AbortSignal }
) => Promise<HookJSONOutput>;
```

<h3 id="hookcallbackmatcher">
  `HookCallbackMatcher`
</h3>

Configuración de hook con coincidencia opcional.

```typescript theme={null}
interface HookCallbackMatcher {
  matcher?: string;
  hooks: HookCallback[];
  timeout?: number; // Tiempo de espera en segundos para todos los hooks en este coincididor
}
```

<h3 id="hookinput">
  `HookInput`
</h3>

Tipo de unión de todos los tipos de entrada de hook.

```typescript theme={null}
type HookInput =
  | PreToolUseHookInput
  | PostToolUseHookInput
  | PostToolUseFailureHookInput
  | PostToolBatchHookInput
  | PermissionDeniedHookInput
  | NotificationHookInput
  | UserPromptSubmitHookInput
  | UserPromptExpansionHookInput
  | SessionStartHookInput
  | SessionEndHookInput
  | StopHookInput
  | StopFailureHookInput
  | SubagentStartHookInput
  | SubagentStopHookInput
  | PreCompactHookInput
  | PostCompactHookInput
  | PreModelSwitchHookInput
  | PostModelSwitchHookInput
  | PermissionRequestHookInput
  | SetupHookInput
  | TeammateIdleHookInput
  | TaskCreatedHookInput
  | TaskCompletedHookInput
  | ElicitationHookInput
  | ElicitationResultHookInput
  | ConfigChangeHookInput
  | InstructionsLoadedHookInput
  | DirectoryAddedHookInput
  | WorktreeCreateHookInput
  | WorktreeRemoveHookInput
  | CwdChangedHookInput
  | FileChangedHookInput
  | MessageDisplayHookInput;
```

<h3 id="basehookinput">
  `BaseHookInput`
</h3>

Interfaz base que todos los tipos de entrada de hook extienden.

```typescript theme={null}
type BaseHookInput = {
  session_id: string;
  transcript_path: string;
  cwd: string;
  prompt_id?: string;
  permission_mode?: string;
  effort?: { level: string };
  agent_id?: string;
  agent_type?: string;
};
```

El campo `prompt_id` es un UUID que identifica el mensaje del usuario que se está procesando actualmente. Coincide con el [atributo `prompt.id` en eventos de OpenTelemetry](/docs/es/monitoring-usage#event-correlation-attributes) y está ausente hasta la primera entrada del usuario. Requiere Claude Code v2.1.196 o posterior.

<h4 id="pretoolusehookinput">
  `PreToolUseHookInput`
</h4>

```typescript theme={null}
type PreToolUseHookInput = BaseHookInput & {
  hook_event_name: "PreToolUse";
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  mcp_server?: McpServerProvenance;
};
```

`mcp_server` está presente cuando la herramienta proviene de un servidor MCP; vea [`McpServerProvenance`](#mcpserverprovenance). Las entradas `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` y `PermissionDenied` llevan el mismo campo. El campo requiere Agent SDK v0.3.274 o posterior.

<h4 id="posttoolusehookinput">
  `PostToolUseHookInput`
</h4>

```typescript theme={null}
type PostToolUseHookInput = BaseHookInput & {
  hook_event_name: "PostToolUse";
  tool_name: string;
  tool_input: unknown;
  tool_response: unknown;
  tool_use_id: string;
  duration_ms?: number;
  mcp_server?: McpServerProvenance;
};
```

<h4 id="posttoolusefailurehookinput">
  `PostToolUseFailureHookInput`
</h4>

```typescript theme={null}
type PostToolUseFailureHookInput = BaseHookInput & {
  hook_event_name: "PostToolUseFailure";
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  error: string;
  is_interrupt?: boolean;
  duration_ms?: number;
  mcp_server?: McpServerProvenance;
};
```

<h4 id="posttoolbatchhookinput">
  `PostToolBatchHookInput`
</h4>

Se activa una vez después de que cada llamada de herramienta en un lote se haya resuelto, antes de la siguiente solicitud del modelo. `tool_response` lleva el contenido serializado de `tool_result` que el modelo ve; la forma difiere del objeto `Output` estructurado de `PostToolUseHookInput`.

```typescript theme={null}
type PostToolBatchHookInput = BaseHookInput & {
  hook_event_name: "PostToolBatch";
  tool_calls: PostToolBatchToolCall[];
};

type PostToolBatchToolCall = {
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  tool_response?: unknown;
};
```

<h4 id="permissiondeniedhookinput">
  `PermissionDeniedHookInput`
</h4>

```typescript theme={null}
type PermissionDeniedHookInput = BaseHookInput & {
  hook_event_name: "PermissionDenied";
  tool_name: string;
  tool_input: unknown;
  tool_use_id: string;
  reason: string;
  mcp_server?: McpServerProvenance;
};
```

<h4 id="notificationhookinput">
  `NotificationHookInput`
</h4>

```typescript theme={null}
type NotificationHookInput = BaseHookInput & {
  hook_event_name: "Notification";
  message: string;
  title?: string;
  notification_type: string;
};
```

<h4 id="userpromptsubmithookinput">
  `UserPromptSubmitHookInput`
</h4>

```typescript theme={null}
type UserPromptSubmitHookInput = BaseHookInput & {
  hook_event_name: "UserPromptSubmit";
  prompt: string;
  session_title?: string;
};
```

<h4 id="userpromptexpansionhookinput">
  `UserPromptExpansionHookInput`
</h4>

```typescript theme={null}
type UserPromptExpansionHookInput = BaseHookInput & {
  hook_event_name: "UserPromptExpansion";
  expansion_type: "slash_command" | "mcp_prompt";
  command_name: string;
  command_args: string;
  command_source?: string;
  prompt: string;
};
```

<h4 id="sessionstarthookinput">
  `SessionStartHookInput`
</h4>

```typescript theme={null}
type SessionStartHookInput = BaseHookInput & {
  hook_event_name: "SessionStart";
  source: "startup" | "resume" | "clear" | "compact" | "fork";
  agent_type?: string;
  model?: string;
  session_title?: string;
};
```

<h4 id="sessionendhookinput">
  `SessionEndHookInput`
</h4>

```typescript theme={null}
type SessionEndHookInput = BaseHookInput & {
  hook_event_name: "SessionEnd";
  reason: ExitReason; // Cadena de matriz EXIT_REASONS
};
```

<h4 id="stophookinput">
  `StopHookInput`
</h4>

```typescript theme={null}
type StopHookInput = BaseHookInput & {
  hook_event_name: "Stop";
  stop_hook_active: boolean;
  last_assistant_message?: string;
  background_tasks?: BackgroundTaskSummary[];
  session_crons?: SessionCronSummary[];
};
```

<h4 id="stopfailurehookinput">
  `StopFailureHookInput`
</h4>

```typescript theme={null}
type StopFailureHookInput = BaseHookInput & {
  hook_event_name: "StopFailure";
  error: SDKAssistantMessageError;
  error_details?: string;
  last_assistant_message?: string;
};
```

<h4 id="subagentstarthookinput">
  `SubagentStartHookInput`
</h4>

```typescript theme={null}
type SubagentStartHookInput = BaseHookInput & {
  hook_event_name: "SubagentStart";
  agent_id: string;
  agent_type: string;
};
```

<h4 id="subagentstophookinput">
  `SubagentStopHookInput`
</h4>

```typescript theme={null}
type SubagentStopHookInput = BaseHookInput & {
  hook_event_name: "SubagentStop";
  stop_hook_active: boolean;
  agent_id: string;
  agent_transcript_path: string;
  agent_type: string;
  last_assistant_message?: string;
  background_tasks?: BackgroundTaskSummary[];
  session_crons?: SessionCronSummary[];
};

type BackgroundTaskSummary = {
  id: string;
  type: string;
  status: string;
  description: string;
  command?: string;
  agent_type?: string;
  server?: string;
  tool?: string;
  name?: string;
};

type SessionCronSummary = {
  id: string;
  schedule: string;
  recurring: boolean;
  prompt: string;
};
```

<h4 id="precompacthookinput">
  `PreCompactHookInput`
</h4>

```typescript theme={null}
type PreCompactHookInput = BaseHookInput & {
  hook_event_name: "PreCompact";
  trigger: "manual" | "auto";
  custom_instructions: string | null;
};
```

<h4 id="postcompacthookinput">
  `PostCompactHookInput`
</h4>

```typescript theme={null}
type PostCompactHookInput = BaseHookInput & {
  hook_event_name: "PostCompact";
  trigger: "manual" | "auto";
  compact_summary: string;
};
```

<h4 id="premodelswitchhookinput">
  `PreModelSwitchHookInput`
</h4>

Se activa antes de que un cambio de modelo solicitado surta efecto. `context_tokens` y los campos posteriores estiman lo que cuesta reenviar la conversación al nuevo modelo. Para las descripciones completas de campos y semántica de bloqueo, vea [PreModelSwitch](/docs/es/hooks#premodelswitch).

```typescript theme={null}
type PreModelSwitchHookInput = BaseHookInput & {
  hook_event_name: "PreModelSwitch";
  from_model: string;
  to_model: string;
  requested_model: string | null;
  source: "command" | "picker" | "sdk";
  context_tokens: number;
  prompt_cache_warm: boolean;
  cache_ttl: "5m" | "1h";
  estimated_cache_write_usd: number;
  pricing: "configured" | "catalog" | "default";
};
```

<h4 id="postmodelswitchhookinput">
  `PostModelSwitchHookInput`
</h4>

Se activa después de que el modelo de la sesión cambia. Lleva los mismos campos que `PreModelSwitchHookInput`, con dos valores de `source` más. Vea [PostModelSwitch](/docs/es/hooks#postmodelswitch).

```typescript theme={null}
type PostModelSwitchHookInput = BaseHookInput & {
  hook_event_name: "PostModelSwitch";
  from_model: string;
  to_model: string;
  requested_model: string | null;
  source: "command" | "picker" | "sdk" | "auto" | "resume";
  context_tokens: number;
  prompt_cache_warm: boolean;
  cache_ttl: "5m" | "1h";
  estimated_cache_write_usd: number;
  pricing: "configured" | "catalog" | "default";
};
```

<h4 id="permissionrequesthookinput">
  `PermissionRequestHookInput`
</h4>

```typescript theme={null}
type PermissionRequestHookInput = BaseHookInput & {
  hook_event_name: "PermissionRequest";
  tool_name: string;
  tool_input: unknown;
  permission_suggestions?: PermissionUpdate[];
  mcp_server?: McpServerProvenance;
};
```

<h4 id="setuphookinput">
  `SetupHookInput`
</h4>

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

<h4 id="teammateidlehookinput">
  `TeammateIdleHookInput`
</h4>

```typescript theme={null}
type TeammateIdleHookInput = BaseHookInput & {
  hook_event_name: "TeammateIdle";
  teammate_name: string;
  /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */
  team_name: string;
};
```

<h4 id="taskcreatedhookinput">
  `TaskCreatedHookInput`
</h4>

```typescript theme={null}
type TaskCreatedHookInput = BaseHookInput & {
  hook_event_name: "TaskCreated";
  task_id: string;
  task_subject: string;
  task_description?: string;
  teammate_name?: string;
  /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */
  team_name?: string;
};
```

<h4 id="taskcompletedhookinput">
  `TaskCompletedHookInput`
</h4>

```typescript theme={null}
type TaskCompletedHookInput = BaseHookInput & {
  hook_event_name: "TaskCompleted";
  task_id: string;
  task_subject: string;
  task_description?: string;
  teammate_name?: string;
  /** @deprecated since v2.1.178. Carries the session-derived team name; will be removed. */
  team_name?: string;
};
```

<h4 id="elicitationhookinput">
  `ElicitationHookInput`
</h4>

```typescript theme={null}
type ElicitationHookInput = BaseHookInput & {
  hook_event_name: "Elicitation";
  mcp_server_name: string;
  message: string;
  mode?: "form" | "url";
  url?: string;
  elicitation_id?: string;
  requested_schema?: Record<string, unknown>;
};
```

<h4 id="elicitationresulthookinput">
  `ElicitationResultHookInput`
</h4>

```typescript theme={null}
type ElicitationResultHookInput = BaseHookInput & {
  hook_event_name: "ElicitationResult";
  mcp_server_name: string;
  elicitation_id?: string;
  mode?: "form" | "url";
  action: "accept" | "decline" | "cancel";
  content?: Record<string, unknown>;
};
```

<h4 id="configchangehookinput">
  `ConfigChangeHookInput`
</h4>

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

<h4 id="instructionsloadedhookinput">
  `InstructionsLoadedHookInput`
</h4>

```typescript theme={null}
type InstructionsLoadedHookInput = BaseHookInput & {
  hook_event_name: "InstructionsLoaded";
  file_path: string;
  memory_type: "User" | "Project" | "Local" | "Managed";
  load_reason:
    | "session_start"
    | "nested_traversal"
    | "path_glob_match"
    | "include"
    | "compact";
  globs?: string[];
  trigger_file_path?: string;
  parent_file_path?: string;
};
```

<h4 id="directoryaddedhookinput">
  `DirectoryAddedHookInput`
</h4>

```typescript theme={null}
type DirectoryAddedHookInput = BaseHookInput & {
  hook_event_name: "DirectoryAdded";
  directory: string;
  source: "slash_command" | "register_repo_root";
};
```

`directory` es la ruta absoluta del directorio que se agregó. `source` es `"slash_command"` cuando `/add-dir` lo agregó y `"register_repo_root"` cuando la solicitud de control del SDK lo hizo.

<h4 id="worktreecreatehookinput">
  `WorktreeCreateHookInput`
</h4>

```typescript theme={null}
type WorktreeCreateHookInput = BaseHookInput & {
  hook_event_name: "WorktreeCreate";
  name: string;
};
```

<h4 id="worktreeremovehookinput">
  `WorktreeRemoveHookInput`
</h4>

```typescript theme={null}
type WorktreeRemoveHookInput = BaseHookInput & {
  hook_event_name: "WorktreeRemove";
  worktree_path: string;
};
```

<h4 id="cwdchangedhookinput">
  `CwdChangedHookInput`
</h4>

```typescript theme={null}
type CwdChangedHookInput = BaseHookInput & {
  hook_event_name: "CwdChanged";
  old_cwd: string;
  new_cwd: string;
};
```

<h4 id="filechangedhookinput">
  `FileChangedHookInput`
</h4>

```typescript theme={null}
type FileChangedHookInput = BaseHookInput & {
  hook_event_name: "FileChanged";
  file_path: string;
  event: "change" | "add" | "unlink";
};
```

<h4 id="messagedisplayhookinput">
  `MessageDisplayHookInput`
</h4>

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

<h3 id="hookjsonoutput">
  `HookJSONOutput`
</h3>

Valor de retorno de hook.

```typescript theme={null}
type HookJSONOutput = AsyncHookJSONOutput | SyncHookJSONOutput;
```

<h4 id="asynchookjsonoutput">
  `AsyncHookJSONOutput`
</h4>

```typescript theme={null}
type AsyncHookJSONOutput = {
  async: true;
  asyncTimeout?: number;
};
```

<h4 id="synchookjsonoutput">
  `SyncHookJSONOutput`
</h4>

```typescript theme={null}
type SyncHookJSONOutput = {
  continue?: boolean;
  suppressOutput?: boolean;
  stopReason?: string;
  decision?: "approve" | "block";
  systemMessage?: string;
  /**
   * Una secuencia de escape de terminal (p. ej. OSC 9 / OSC 777 notificación de escritorio)
   * para que Claude Code emita en su nombre. Solo se permiten OSCs de notificación/título
   * (0, 1, 2, 9, 99, 777) y BEL; un valor que contenga cualquier otra cosa se ignora en su totalidad. Solo la CLI interactiva lo emite;
   * el SDK ignora el campo.
   */
  terminalSequence?: string;
  reason?: string;
  hookSpecificOutput?:
    | {
        hookEventName: "PreToolUse";
        permissionDecision?: "allow" | "deny" | "ask" | "defer";
        permissionDecisionReason?: string;
        updatedInput?: Record<string, unknown>;
        additionalContext?: string;
      }
    | {
        hookEventName: "UserPromptSubmit";
        additionalContext?: string;
        sessionTitle?: string;
        /** Cuando la decisión es "block", omita el mensaje original del bloque. */
        suppressOriginalPrompt?: boolean;
      }
    | {
        hookEventName: "UserPromptExpansion";
        additionalContext?: string;
      }
    | {
        hookEventName: "SessionStart";
        additionalContext?: string;
        initialUserMessage?: string;
        sessionTitle?: string;
        watchPaths?: string[];
        /**
         * Vuelva a escanear los directorios de skill y comando después de que se completen los hooks de SessionStart,
         * para que los skills instalados por el hook estén disponibles en la
         * misma sesión.
         */
        reloadSkills?: boolean;
      }
    | {
        hookEventName: "Setup";
        additionalContext?: string;
      }
    | {
        hookEventName: "PreModelSwitch";
        /**
         * El mismo contrato que PreToolUse: "allow" procede, "deny" cancela
         * el cambio, "ask" le pide al usuario que confirme. Solo /model en una
         * sesión interactiva muestra ese mensaje; todas las otras superficies,
         * incluidas las solicitudes set_model, tratan "ask" como un rechazo.
         */
        permissionDecision?: "allow" | "deny" | "ask";
        permissionDecisionReason?: string;
      }
    | {
        hookEventName: "PostModelSwitch";
        /** Llega al modelo con la siguiente solicitud que sirve el nuevo modelo. */
        additionalContext?: string;
      }
    | {
        hookEventName: "SubagentStart";
        additionalContext?: string;
      }
    | {
        hookEventName: "PostToolUse";
        additionalContext?: string;
        /**
         * Nota breve sobre el resultado de esta llamada de herramienta para el clasificador de permisos del modo automático. Limitado a 2000 caracteres, compartido entre
         * todos los hooks que responden a la misma llamada; honrado solo en respuestas de hooks síncronos. No copie salida de herramienta no confiable en él.
         */
        classifierContext?: string;
        updatedToolOutput?: unknown;
        /** @deprecated Use `updatedToolOutput`, which works for all tools. */
        updatedMCPToolOutput?: unknown;
      }
    | {
        hookEventName: "PostToolUseFailure";
        additionalContext?: string;
      }
    | {
        hookEventName: "PostToolBatch";
        additionalContext?: string;
      }
    | {
        hookEventName: "Stop";
        additionalContext?: string;
      }
    | {
        hookEventName: "SubagentStop";
        additionalContext?: string;
      }
    | {
        hookEventName: "PermissionDenied";
        retry?: boolean;
      }
    | {
        hookEventName: "Notification";
        additionalContext?: string;
      }
    | {
        hookEventName: "PermissionRequest";
        decision:
          | {
              behavior: "allow";
              updatedInput?: Record<string, unknown>;
              updatedPermissions?: PermissionUpdate[];
            }
          | {
              behavior: "deny";
              message?: string;
              interrupt?: boolean;
            };
      }
    | {
        hookEventName: "Elicitation";
        action?: "accept" | "decline" | "cancel";
        content?: Record<string, unknown>;
      }
    | {
        hookEventName: "ElicitationResult";
        action?: "accept" | "decline" | "cancel";
        content?: Record<string, unknown>;
      }
    | {
        hookEventName: "CwdChanged";
        watchPaths?: string[];
      }
    | {
        hookEventName: "FileChanged";
        watchPaths?: string[];
      }
    | {
        hookEventName: "WorktreeCreate";
        worktreePath: string;
      }
    | {
        hookEventName: "MessageDisplay";
        /** Texto mostrado en lugar del delta. Omita (o devuelva el delta sin cambios) para mostrar el original. */
        displayContent?: string;
      };
};
```

<h2 id="tool-input-types">
  Tipos de Entrada de Herramienta
</h2>

Documentación de esquemas de entrada para todas las herramientas integradas de Claude Code. Estos tipos se exportan desde `@anthropic-ai/claude-agent-sdk/sdk-tools` y se pueden usar para interacciones de herramientas seguras de tipos.

<h3 id="toolinputschemas">
  `ToolInputSchemas`
</h3>

Unión de tipos de entrada de herramienta exportados desde `@anthropic-ai/claude-agent-sdk/sdk-tools`; los miembros incluyen:

```typescript theme={null}
type ToolInputSchemas =
  | AgentInput
  | ArtifactInput
  | AskUserQuestionInput
  | BashInput
  | CronCreateInput
  | CronDeleteInput
  | CronListInput
  | EnterPlanModeInput
  | EnterWorktreeInput
  | ExitPlanModeInput
  | ExitWorktreeInput
  | FileEditInput
  | FileReadInput
  | FileWriteInput
  | GlobInput
  | GrepInput
  | ListMcpResourcesInput
  | McpInput
  | MonitorInput
  | NotebookEditInput
  | ProjectsInput
  | PushNotificationInput
  | ReadMcpResourceDirInput
  | ReadMcpResourceInput
  | RefreshMcpToolsInput
  | RemoteTriggerInput
  | ReportFindingsInput
  | ScheduleWakeupInput
  | ShowOnboardingRolePickerInput
  | TaskCreateInput
  | TaskGetInput
  | TaskListInput
  | TaskStopInput
  | TaskUpdateInput
  | TodoWriteInput
  | WebFetchInput
  | WebSearchInput
  | WorkflowInput;
```

<h3 id="agent">
  Agent
</h3>

**Nombre de herramienta:** `Agent`. El nombre anterior `Task` aún se acepta como alias, y el array `tools` en el mensaje de inicialización [`SDKSystemMessage`](#sdksystemmessage) actualmente enumera esta herramienta como `Task` para compatibilidad hacia atrás.

<Note>
  El campo `mode` está deprecado e ignorado en Claude Code v2.1.212 o posterior. Un subagente se ejecuta en el modo de permiso de la sesión padre o en la [`permissionMode`](#agentdefinition) de su definición, y las [reglas de herencia de subagentes](/docs/es/agent-sdk/permissions#available-modes) deciden cuál.
</Note>

```typescript theme={null}
type AgentInput = {
  description: string;
  prompt: string;
  subagent_type?: string;
  model?: "sonnet" | "opus" | "haiku" | "fable";
  run_in_background?: boolean;
  name?: string;
  team_name?: string; // Deprecated; ignored
  mode?: "acceptEdits" | "auto" | "bypassPermissions" | "default" | "dontAsk" | "plan"; // Deprecated; ignored. The subagent inheritance rules decide a subagent's permission mode
  isolation?: "worktree" | "remote";
};
```

Lanza un nuevo agente para manejar tareas complejas de múltiples pasos de forma autónoma.

<h3 id="askuserquestion">
  AskUserQuestion
</h3>

**Nombre de herramienta:** `AskUserQuestion`

```typescript theme={null}
type AskUserQuestionInput = {
  questions: Array<{
    question: string;
    header: string;
    options: Array<{ label: string; description: string; preview?: string }>;
    multiSelect: boolean;
  }>;
  answers?: Record<string, string>;
  annotations?: Record<string, { preview?: string; notes?: string }>;
  metadata?: { source?: string };
};
```

Hace preguntas aclaratorias al usuario durante la ejecución. Vea [Manejar aprobaciones e entrada del usuario](/docs/es/agent-sdk/user-input#handle-clarifying-questions) para detalles de uso.

<h3 id="bash">
  Bash
</h3>

**Nombre de herramienta:** `Bash`

```typescript theme={null}
type BashInput = {
  command: string;
  timeout?: number; // milliseconds. Foreground: capped at 600000 by default, higher values are clamped. With run_in_background (Claude Code v2.1.285 or later): the background time limit, 1800000 when omitted, capped at 7200000 unless raised
  description?: string;
  run_in_background?: boolean;
  dangerouslyDisableSandbox?: boolean;
};
```

Ejecuta comandos Bash con tiempo de espera opcional y ejecución en segundo plano. El directorio de trabajo persiste entre comandos, incluyendo comandos ejecutados en turnos posteriores de una sesión de múltiples turnos; el estado del shell como variables de entorno exportadas no. Para los límites sobre qué cambios de directorio se mantienen, vea [Lo que persiste entre comandos](/docs/es/tools-reference#what-persists-between-commands). Para lo que establece el límite de primer plano, vea [Límites de tiempo de espera y salida](/docs/es/tools-reference#timeout-and-output-limits). Para el límite de tiempo en segundo plano, vea [Límite de tiempo para comandos en segundo plano](/docs/es/tools-reference#time-limit-for-background-commands).

<h3 id="monitor">
  Monitor
</h3>

**Nombre de herramienta:** `Monitor`

```typescript theme={null}
type MonitorInput = {
  description: string;
  timeout_ms: number;
  command?: string;
  ws?: {
    url: string;
    protocols?: string[];
  };
};
```

Ejecuta una fuente de fondo y entrega cada evento a Claude para que pueda reaccionar sin sondeo: `command` ejecuta un script y emite un evento por línea de stdout, y `ws` abre un WebSocket y emite un evento por marco de texto. Proporcione exactamente uno de `command` o `ws`. La fuente `ws` requiere Claude Code v2.1.195 o posterior.

`timeout_ms` es el plazo de la vigilancia en milisegundos. El valor predeterminado es 300000 y acepta valores hasta 3600000. El plazo efectivo es como máximo 1800000, que son 30 minutos, por lo que un valor aceptado más grande se acorta a eso. En el plazo, la vigilancia termina y Claude recibe un aviso para que pueda iniciar una nueva vigilancia si aún la necesita.

El tipo exportado marca `timeout_ms` como requerido porque el esquema completa el valor predeterminado; una llamada que lo omite valida.

Cuando Monitor ejecuta un comando, sigue las mismas reglas de permiso que Bash; una vigilancia de WebSocket solicita aprobación por separado. Vea la [referencia de herramienta Monitor](/docs/es/tools-reference#monitor-tool) para comportamiento y disponibilidad de proveedor.

<h3 id="taskoutput">
  TaskOutput
</h3>

Eliminado en Claude Code v2.1.277, junto con su tipo `TaskOutputInput`. Anteriormente recuperaba salida de una tarea de fondo en ejecución o completada; Claude lee el archivo de salida de una tarea de fondo con `Read` en su lugar.

Una entrada `disallowedTools` o una regla de denegación que aún nombre `TaskOutput` se ignora sin una advertencia.

<h3 id="edit">
  Edit
</h3>

**Nombre de herramienta:** `Edit`

```typescript theme={null}
type FileEditInput = {
  file_path: string;
  old_string: string;
  new_string: string;
  replace_all?: boolean;
};
```

Realiza reemplazos de cadena exactos en archivos.

<h3 id="read">
  Read
</h3>

**Nombre de herramienta:** `Read`

```typescript theme={null}
type FileReadInput = {
  file_path: string;
  offset?: number;
  limit?: number;
  pages?: string;
};
```

Lee archivos del sistema de archivos local, incluyendo texto, imágenes, PDFs y cuadernos Jupyter. Use `pages` para rangos de páginas PDF (por ejemplo, `"1-5"`).

Para un PDF, Claude recibe el contenido del archivo dentro del `tool_result` de la llamada Read. Una lectura que devuelve la salida `pdf` [output](#tool-output-types) lleva un bloque `text` de resumen seguido de un bloque `document`. Una que devuelve la salida `parts` lleva el bloque `text` de resumen seguido de un bloque por página extraída: un bloque `image`, o un bloque `text` nombrando la página cuando Claude Code no pudo renderizarla como imagen. Antes de Agent SDK v0.3.242, Claude Code entregaba el contenido del archivo como un mensaje `user` separado después del resultado de la herramienta.

<h3 id="write">
  Write
</h3>

**Nombre de herramienta:** `Write`

```typescript theme={null}
type FileWriteInput = {
  file_path: string;
  content: string;
};
```

Escribe un archivo en el sistema de archivos local, sobrescribiendo si existe.

<h3 id="glob">
  Glob
</h3>

**Nombre de herramienta:** `Glob`

```typescript theme={null}
type GlobInput = {
  pattern: string;
  path?: string;
};
```

Coincidencia de patrón de archivo rápida que funciona con cualquier tamaño de base de código.

<h3 id="grep">
  Grep
</h3>

**Nombre de herramienta:** `Grep`

```typescript theme={null}
type GrepInput = {
  pattern: string;
  path?: string;
  glob?: string;
  type?: string;
  output_mode?: "content" | "files_with_matches" | "count";
  "-i"?: boolean;
  "-o"?: boolean; // print only the matched parts of each line; requires output_mode: "content"
  "-n"?: boolean;
  "-B"?: number;
  "-A"?: number;
  "-C"?: number;
  context?: number;
  head_limit?: number;
  offset?: number;
  multiline?: boolean;
};
```

Herramienta de búsqueda construida sobre ripgrep con soporte de expresiones regulares.

<h3 id="taskstop">
  TaskStop
</h3>

**Nombre de herramienta:** `TaskStop`

```typescript theme={null}
type TaskStopInput = {
  task_id?: string;
  shell_id?: string; // Deprecated: use task_id
};
```

Detiene una tarea de fondo en ejecución o shell por ID. A partir de v2.1.198, `task_id` también acepta un compañero de equipo de agentes o un agente de fondo nombrado por ID de agente o nombre.

<h3 id="notebookedit">
  NotebookEdit
</h3>

**Nombre de herramienta:** `NotebookEdit`

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

Edita celdas en archivos de cuaderno Jupyter.

<h3 id="webfetch">
  WebFetch
</h3>

**Nombre de herramienta:** `WebFetch`

```typescript theme={null}
type WebFetchInput = {
  url: string;
  prompt: string;
};
```

Obtiene contenido de una URL y lo procesa con un modelo de IA.

<h3 id="websearch">
  WebSearch
</h3>

**Nombre de herramienta:** `WebSearch`

```typescript theme={null}
type WebSearchInput = {
  query: string;
  allowed_domains?: string[];
  blocked_domains?: string[];
};
```

Busca en la web y devuelve resultados formateados.

<h3 id="workflow">
  Workflow
</h3>

**Nombre de herramienta:** `Workflow`

```typescript theme={null}
type WorkflowInput = {
  script?: string;
  name?: string;
  scriptPath?: string;
  args?: unknown; // any JSON value; the published typings render this as an object map
  resumeFromRunId?: string;
  title?: string; // ignored; the script's meta block sets the title
  description?: string; // ignored; the script's meta block sets the description
};
```

Ejecuta un [flujo de trabajo dinámico](/docs/es/workflows): un script que orquesta muchos subagentes en segundo plano y devuelve un resultado consolidado. La herramienta `Workflow` está disponible en Agent SDK v0.3.149 y posterior. Se requiere al menos uno de `script`, `name` o `scriptPath`.

| Campo | Tipo | Descripción |
| - | - | - |
| `script` | `string` | Script de flujo de trabajo en línea. Debe comenzar con `export const meta = { name, description }` como un literal, seguido del cuerpo del script usando `agent()`, `parallel()`, `pipeline()` y `phase()`. Una matriz `phases` opcional en `meta` agrupa agentes bajo etapas nombradas en la vista de progreso |
| `name` | `string` | Nombre de un flujo de trabajo integrado o uno guardado en `.claude/workflows/`. Se resuelve a un script |
| `scriptPath` | `string` | Ruta a un archivo de script de flujo de trabajo en disco. Tiene precedencia sobre `script` y `name`. Claude Code persiste cada invocación de script y devuelve la ruta en el resultado, para que pueda editar ese archivo e invocar nuevamente con el mismo `scriptPath` para iterar |
| `args` | `unknown` | Valor de entrada expuesto al script como el `args` global, para flujos de trabajo nombrados parametrizados como una pregunta de investigación o una lista de rutas de archivo. Pase matrices y objetos como valores JSON reales, no como una cadena codificada en JSON |
| `resumeFromRunId` | `string` | ID de ejecución de una invocación anterior de `Workflow` para reanudar. Las llamadas `agent()` completadas con entradas sin cambios devuelven resultados en caché; el resto se ejecuta en vivo. [Reanudar después de una pausa](/docs/es/workflows#resume-after-a-pause) cubre qué llamadas completadas se re-ejecutan. Solo la misma sesión |
| `title` | `string` | Ignorado; el bloque `meta` del script establece el título |
| `description` | `string` | Ignorado; el bloque `meta` del script establece la descripción |

<h3 id="todowrite">
  TodoWrite
</h3>

**Nombre de herramienta:** `TodoWrite`

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

Crea y gestiona una lista de tareas estructurada para rastrear el progreso.

<Note>
  Las siguientes herramientas están disponibles por defecto solo en modelos Claude 3.x, Opus 4 a través de 4.7, Sonnet 4 a través de 4.6 y Haiku 4.5. En todos los demás modelos, incluidos los ID de modelo que Claude Code no reconoce, no están disponibles a menos que opte por incluirlas:

  * `TodoWrite`
  * `TaskCreate`
  * `TaskGet`
  * `TaskUpdate`
  * `TaskList`

  Dondequiera que las herramientas estén disponibles, Claude Code proporciona las cuatro herramientas Task, o `TodoWrite` en su lugar cuando establece `CLAUDE_CODE_ENABLE_TASKS=0`.

  Este conjunto predeterminado se aplica en Claude Code v2.1.268 y posterior, que el TypeScript Agent SDK agrupa desde v0.3.268.

  Vea [Disponibilidad de modelo](/docs/es/agent-sdk/todo-tracking#model-availability) para optar por participar.
</Note>

<h3 id="taskcreate">
  TaskCreate
</h3>

**Nombre de herramienta:** `TaskCreate`

```typescript theme={null}
type TaskCreateInput = {
  subject: string;
  description: string;
  activeForm?: string;
  metadata?: Record<string, unknown>;
};
```

Crea una única tarea y devuelve su ID asignado.

<h3 id="taskupdate">
  TaskUpdate
</h3>

**Nombre de herramienta:** `TaskUpdate`

```typescript theme={null}
type TaskUpdateInput = {
  taskId: string;
  status?: "pending" | "in_progress" | "completed" | "deleted";
  subject?: string;
  description?: string;
  activeForm?: string;
  addBlocks?: string[];
  addBlockedBy?: string[];
  owner?: string;
  metadata?: Record<string, unknown>;
};
```

Parcha una tarea por ID. Establezca `status` a `"deleted"` para eliminarla.

<h3 id="taskget">
  TaskGet
</h3>

**Nombre de herramienta:** `TaskGet`

```typescript theme={null}
type TaskGetInput = {
  taskId: string;
};
```

Devuelve detalles completos para una tarea, o `null` cuando el ID no se encuentra.

<h3 id="tasklist">
  TaskList
</h3>

**Nombre de herramienta:** `TaskList`

```typescript theme={null}
type TaskListInput = {};
```

Devuelve una instantánea de todas las tareas en la lista actual.

<h3 id="exitplanmode">
  ExitPlanMode
</h3>

**Nombre de herramienta:** `ExitPlanMode`

```typescript theme={null}
type ExitPlanModeInput = {
  /** Deprecated: no longer used. */
  allowedPrompts?: Array<{
    tool: "Bash";
    prompt: string;
  }>;
  [k: string]: unknown;
};
```

Sale del modo de planificación. El campo `allowedPrompts` está deprecado e ignorado; Claude Code aún lo acepta para que los llamadores existentes y las transcripciones se validen. Antes de v2.1.205, solicitaba permisos de Bash basados en mensajes para implementar el plan.

<h3 id="listmcpresources">
  ListMcpResources
</h3>

**Nombre de herramienta:** `ListMcpResourcesTool`

```typescript theme={null}
type ListMcpResourcesInput = {
  server?: string;
};
```

Enumera recursos MCP disponibles de servidores conectados.

<h3 id="readmcpresource">
  ReadMcpResource
</h3>

**Nombre de herramienta:** `ReadMcpResourceTool`

```typescript theme={null}
type ReadMcpResourceInput = {
  server: string;
  uri: string;
};
```

Lee un recurso MCP específico de un servidor.

<h3 id="enterworktree">
  EnterWorktree
</h3>

**Nombre de herramienta:** `EnterWorktree`

```typescript theme={null}
type EnterWorktreeInput = {
  name?: string;
  path?: string;
};
```

Crea e ingresa a un worktree git temporal para trabajo aislado. Pase `path` para cambiar a un worktree existente en lugar de crear uno nuevo. En la primera entrada, el destino debe ser un worktree registrado del repositorio actual o, en un espacio de trabajo de múltiples repositorios, de un repositorio anidado dentro de él; desde dentro de una sesión de worktree debe estar bajo `.claude/worktrees/` del repositorio de la sesión. `name` y `path` son mutuamente excluyentes.

<h3 id="exitworktree">
  ExitWorktree
</h3>

**Nombre de herramienta:** `ExitWorktree`

```typescript theme={null}
type ExitWorktreeInput = {
  action: "keep" | "remove";
  discard_changes?: boolean;
};
```

Sale del worktree git actual y regresa al directorio de trabajo original. La acción `keep` deja el worktree y la rama en disco, mientras que `remove` elimina ambos. `discard_changes` debe ser `true` cuando se elimina un worktree que tiene archivos sin confirmar o commits sin fusionar.

<h3 id="enterplanmode">
  EnterPlanMode
</h3>

**Nombre de herramienta:** `EnterPlanMode`

```typescript theme={null}
type EnterPlanModeInput = {};
```

Entra en modo de planificación, donde Claude investiga y presenta un plan antes de hacer cambios.

<h3 id="croncreate">
  CronCreate
</h3>

**Nombre de herramienta:** `CronCreate`

```typescript theme={null}
type CronCreateInput = {
  cron: string;
  prompt: string;
  recurring?: boolean;
  durable?: boolean;
};
```

Programa un mensaje para ejecutarse en un cronograma cron de 5 campos en hora local. Establezca `recurring` a `false` para dispararse una vez en la siguiente coincidencia. Los trabajos tienen alcance de sesión de forma predeterminada, y reanudar con `--resume` o `--continue` restaura trabajos que no han expirado. Vea [Tareas programadas](/docs/es/scheduled-tasks).

Establecer `durable` a `true` solicita persistencia a `.claude/scheduled_tasks.json` para que el trabajo sobreviva a los reinicios. La programación durable no está disponible en todas las sesiones: cuando no lo está, Claude Code acepta `durable: true` pero crea el trabajo solo de sesión. Lea el campo `durable` de la salida para ver si el trabajo persistió.

<h3 id="crondelete">
  CronDelete
</h3>

**Nombre de herramienta:** `CronDelete`

```typescript theme={null}
type CronDeleteInput = {
  id: string;
};
```

Elimina un trabajo cron programado por el ID devuelto desde `CronCreate`.

<h3 id="cronlist">
  CronList
</h3>

**Nombre de herramienta:** `CronList`

```typescript theme={null}
type CronListInput = {};
```

Enumera los trabajos cron programados: trabajos duraderos desde `.claude/scheduled_tasks.json` y trabajos solo de sesión desde la sesión actual.

<h3 id="schedulewakeup">
  ScheduleWakeup
</h3>

**Nombre de herramienta:** `ScheduleWakeup`

```typescript theme={null}
type ScheduleWakeupInput = {
  delaySeconds?: number;
  reason?: string;
  prompt?: string;
  noop?: boolean;
  stop?: boolean;
};
```

Programa un despertar de una sola vez que dispara el mensaje dado después de un retraso. Esta herramienta respalda el comando `/loop` de ritmo propio. El tiempo de ejecución fija `delaySeconds` entre 60 y 3600 segundos. Los campos `delaySeconds`, `reason`, `prompt` y `noop` son requeridos a menos que `stop` sea true. `noop: true` reporta un despertar donde nada cambió. Establecer `stop: true` cancela el despertar pendiente y finaliza el `/loop` de ritmo propio. El campo `stop` requiere Claude Code v2.1.202 o posterior. Vea la [fila ScheduleWakeup en la referencia de herramientas](/docs/es/tools-reference).

<h3 id="remotetrigger">
  RemoteTrigger
</h3>

**Nombre de herramienta:** `RemoteTrigger`

```typescript theme={null}
type RemoteTriggerInput = {
  action:
    | "list"
    | "get"
    | "create"
    | "update"
    | "run"
    | "create_webhook_trigger"
    | "list_runs"
    | "get_run_log";
  trigger_id?: string;
  session_id?: string;
  cursor?: string;
  body?: {
    [k: string]: unknown;
  };
};
```

Gestiona [Rutinas](/docs/es/routines), las ejecuciones de Claude Code programadas y activadas alojadas en la nube. Esta herramienta respalda el comando `/schedule`. `trigger_id` es requerido para las acciones `get`, `update`, `run` y `list_runs`. `body` es requerido para `create`, `update` y `create_webhook_trigger`, y opcional para `run`.

`create_webhook_trigger` adjunta una fuente de evento a una rutina existente, como un [evento de GitHub](/docs/es/routines#add-a-github-trigger) que la dispara. El `body` nombra la fuente, los eventos y la rutina a disparar. Requiere Claude Code v2.1.225 o posterior.

`list_runs` enumera las ejecuciones recientes de una rutina, y `get_run_log` lee el registro de una ejecución. `session_id` nombra la ejecución a leer, desde un resultado de `list_runs`, y `cursor` pagina a través de los resultados de cualquiera de las acciones. Ambas acciones requieren Claude Code v2.1.227 o posterior.

Esta herramienta está disponible solo cuando la sesión se autentica con una cuenta claude.ai en un plan con Rutinas habilitadas, y está ausente cuando la política de su organización deshabilita [Claude Code en la web](/docs/es/claude-code-on-the-web). En Claude Code v2.1.227 o posterior, la herramienta también está ausente cuando un Propietario ha [desactivado las rutinas para la organización](/docs/es/routines#routines-are-disabled-by-your-organizations-policy). Antes de v2.1.227, una sesión con solo el interruptor de rutinas desactivado aún mostraba la herramienta, y el servidor denegaba sus llamadas.

<h3 id="pushnotification">
  PushNotification
</h3>

**Nombre de herramienta:** `PushNotification`

```typescript theme={null}
type PushNotificationInput = {
  message: string;
  status: "proactive";
};
```

Envía una notificación push proactiva al usuario. Mantenga `message` bajo 200 caracteres porque los sistemas operativos móviles truncan texto más largo. Vea la [fila PushNotification en la referencia de herramientas](/docs/es/tools-reference) para disponibilidad de proveedor; la entrega push se ejecuta a través de infraestructura alojada por Anthropic que no es accesible desde Amazon Bedrock, Claude Platform en AWS, Agent Platform de Google Cloud o Microsoft Foundry.

<h3 id="repl">
  REPL
</h3>

Eliminado en v2.1.275. A través de v2.1.274, una herramienta `REPL` experimental podría activarse con `CLAUDE_CODE_REPL=1` en la opción [`env`](#options).

<h3 id="reportfindings">
  ReportFindings
</h3>

**Nombre de herramienta:** `ReportFindings`

```typescript theme={null}
type ReportFindingsInput = {
  level?: "low" | "medium" | "high" | "xhigh" | "max";
  findings: Array<{
    file: string;
    line?: number;
    summary: string;
    failure_scenario: string;
    short_summary?: string;
    category?: string;
    verdict?: "CONFIRMED" | "PLAUSIBLE";
    outcome?: "fixed" | "skipped" | "no_change_needed";
  }>;
};
```

Reporta hallazgos de revisión de código como una lista estructurada para que Claude Code pueda renderizarlos en lugar de imprimirlos como texto. `level` es el nivel de esfuerzo en el que se ejecutó la revisión. Los hallazgos se ordenan de más grave a menos grave, con un máximo de 32 por llamada, y el array está vacío cuando ninguno sobrevivió. Requiere Claude Code v2.1.196 o posterior.

Cada hallazgo lleva estos campos:

* `file`: ruta relativa al repositorio en la que está el hallazgo. El `line` opcional es la línea indexada en 1 a la que se ancla.
* `summary`: declaración de una oración del defecto. `failure_scenario` describe las entradas concretas y el estado que conducen a la salida incorrecta o al bloqueo.
* `short_summary`: etiqueta comprimida opcional de como máximo 60 caracteres para visualización compacta. Requiere Claude Code v2.1.212 o posterior.
* `category`: slug kebab-case corto opcional del tipo de hallazgo, como `correctness` o `test-coverage`. Requiere Claude Code v2.1.199 o posterior.
* `verdict`: se establece cuando se ejecutó una pasada de verificación; ausente en revisiones solo en línea.
* `outcome`: se establece solo cuando se reporta nuevamente después de aplicar correcciones.

<h3 id="artifact">
  Artifact
</h3>

**Nombre de herramienta:** `Artifact`

```typescript theme={null}
type ArtifactInput = {
  action?: "publish" | "list";
  file_path?: string;
  favicon?: string;
  icon?: string;
  limit?: number;
  scope?: "mine" | "shared" | "all";
  title?: string;
  description?: string;
  label?: string;
  url?: string;
  force?: boolean;
  capabilities?: Record<string, unknown>;
  contract?: "latest" | string;
};
```

Publica un archivo `.html` o `.md` local como una página de artefacto alojada, o enumera los artefactos publicados del usuario. Omita `action` o pase `"publish"` para publicar `file_path`, que es requerido para la acción de publicación. Cada campo a continuación se aplica a una publicación:

* `icon`: una palabra genérica corta para el icono de pestaña del navegador del artefacto, como `chart` o `map`. Claude lo incluye en una primera publicación y lo omite en una actualización, lo que mantiene el icono almacenado del artefacto.
* `favicon`: deprecado, y Claude lo omite.
* `title`: nombra la página publicada en la pestaña del navegador y la galería cuando el archivo HTML no tiene etiqueta `<title>`.
* `url`: apunta a un artefacto existente para actualizar en su lugar en lugar de crear uno nuevo.

`force` es una sobrescritura de último recurso que descarta una versión más nueva que otra sesión publicó. En un conflicto, la publicación fallida devuelve el contenido más nuevo; Claude fusiona sus cambios en ese contenido, o vuelve a leer el artefacto, y publica nuevamente. Pase `force` solo cuando el usuario solicita explícitamente descartar esa versión.

Pase `"list"` para enumerar los artefactos publicados del usuario; solo `limit` y `scope` pueden acompañarlo. `scope` tiene como valor predeterminado `"mine"`, que enumera artefactos que el usuario posee; `"shared"` enumera artefactos que otras personas compartieron con el usuario, y `"all"` enumera ambos.

* `capabilities`: las capacidades de tiempo de ejecución que usa la página publicada, codificadas por nombre de capacidad, como los [conectores que la página puede llamar](/docs/es/artifacts#pull-live-data-with-mcp-connectors). El servicio de artefactos valida la declaración y rechaza una publicación que nombra una capacidad que la cuenta no puede usar o le da una configuración inválida. Pase `{}` para borrar una declaración almacenada, y omita el campo en un redeploy para mantenerlo. Requiere Agent SDK v0.3.235 o posterior.
* `contract`: la versión de tiempo de ejecución contra la que se ejecuta la página publicada. Omítalo para mantener la versión actual del artefacto, pase `"latest"` para actualizar, o pase una versión específica para fijar o revertir. Requiere Agent SDK v0.3.235 o posterior.

Los tipos se exportan, pero la herramienta está desactivada de forma predeterminada en sesiones de Agent SDK. La publicación también requiere todas las condiciones en la [tabla de disponibilidad de artefactos](/docs/es/artifacts#availability), que las sesiones autenticadas con una clave API no cumplen.

<h3 id="projects">
  Projects
</h3>

**Nombre de herramienta:** `Projects`

```typescript theme={null}
type ProjectsInput = {
  method:
    | "project_info"
    | "project_read"
    | "project_search"
    | "project_write"
    | "project_delete";
  path?: string;
  content?: string;
  local_path?: string;
  present_to_user?: boolean;
  query?: string;
  n?: number;
};
```

Lee y escribe el Proyecto de claude.ai adjunto a la sesión. Distribuye en `method`:

* `project_info`: devuelve metadatos del proyecto y la lista de documentos.
* `project_read`: lee un documento por `path`.
* `project_search`: consulta la base de conocimiento del proyecto con `query`. `n` limita los resultados y tiene como valor predeterminado 5.
* `project_write`: crea o reemplaza un documento en `path` desde exactamente uno de `content`, que lleva texto en línea, o `local_path`, que nombra un archivo dentro del directorio de trabajo. `present_to_user: true` marca el documento escrito como el entregable que el usuario necesita ver.
* `project_delete`: elimina un documento por `path`.

<h3 id="readmcpresourcedir">
  ReadMcpResourceDir
</h3>

**Nombre de herramienta:** `ReadMcpResourceDirTool`

```typescript theme={null}
type ReadMcpResourceDirInput = {
  server: string;
  uri: string;
};
```

Enumera los hijos directos de un recurso de directorio en un servidor MCP. Solo se puede usar contra un servidor que haya declarado soporte para listado de directorios; el listado no es recursivo. El listado de directorios no está habilitado en todas las sesiones: cuando está desactivado, la llamada devuelve una lista `resources` vacía y el campo `error` reporta que el listado de directorios no está habilitado.

<h3 id="refreshmcptools">
  RefreshMcpTools
</h3>

**Nombre de herramienta:** `RefreshMcpTools`

```typescript theme={null}
type RefreshMcpToolsInput = {
  server?: string; // refresh only this server; omit to refresh all connected servers
};
```

Vuelve a consultar la lista de herramientas de servidores MCP conectados y aplica cualquier cambio. Los tipos se exportan, pero Claude Code registra la herramienta solo cuando establece `CLAUDE_CODE_ENABLE_REFRESH_MCP_TOOLS=1` en la opción [`env`](#options), y solo en sesiones con al menos un servidor MCP. Requiere Claude Code v2.1.211 o posterior.

<h3 id="showonboardingrolepicker">
  ShowOnboardingRolePicker
</h3>

**Nombre de herramienta:** `ShowOnboardingRolePicker`

```typescript theme={null}
type ShowOnboardingRolePickerInput = {};
```

Renderiza una fila de chip selector de rol clickeable durante la incorporación de Cowork para que el usuario pueda elegir su rol y obtener un plugin coincidente instalado. No toma argumentos; la lista de roles se define por el cliente. La llamada se bloquea hasta que el usuario responde.

<h3 id="mcpinput">
  McpInput
</h3>

**Nombre de herramienta:** nombres de herramientas MCP dinámicas de la forma `mcp__<server>__<tool>`

```typescript theme={null}
type McpInput = {
  [k: string]: unknown;
};
```

Los argumentos de herramientas MCP son un objeto abierto: cada servidor define sus propios parámetros, por lo que el tipo no coloca restricciones en nombres de campos o valores. Consulte el esquema de herramientas del servidor para los campos que acepta una herramienta específica.

<h2 id="tool-output-types">
  Tipos de salida de herramientas
</h2>

Documentación de los esquemas de salida de todas las herramientas integradas de Claude Code. Estos tipos se exportan desde `@anthropic-ai/claude-agent-sdk/sdk-tools` y representan los datos de respuesta reales que devuelve cada herramienta.

<h3 id="tooloutputschemas">
  `ToolOutputSchemas`
</h3>

Unión de los tipos de salida de herramientas exportados desde `@anthropic-ai/claude-agent-sdk/sdk-tools`; sus miembros incluyen:

```typescript theme={null}
type ToolOutputSchemas =
  | AgentOutput
  | ArtifactOutput
  | AskUserQuestionOutput
  | BashOutput
  | CronCreateOutput
  | CronDeleteOutput
  | CronListOutput
  | EnterPlanModeOutput
  | EnterWorktreeOutput
  | ExitPlanModeOutput
  | ExitWorktreeOutput
  | FileEditOutput
  | FileReadOutput
  | FileWriteOutput
  | GlobOutput
  | GrepOutput
  | ListMcpResourcesOutput
  | McpOutput
  | MonitorOutput
  | NotebookEditOutput
  | ProjectsOutput
  | PushNotificationOutput
  | ReadMcpResourceDirOutput
  | ReadMcpResourceOutput
  | RefreshMcpToolsOutput
  | RemoteTriggerOutput
  | ReportFindingsOutput
  | ScheduleWakeupOutput
  | ShowOnboardingRolePickerOutput
  | TaskCreateOutput
  | TaskGetOutput
  | TaskListOutput
  | TaskStopOutput
  | TaskUpdateOutput
  | TodoWriteOutput
  | WebFetchOutput
  | WebSearchOutput
  | WorkflowOutput;
```

<h3 id="agent-2">
  Agent
</h3>

**Nombre de la herramienta:** `Agent`. El nombre anterior `Task` todavía se acepta como alias, y el array `tools` del mensaje de inicialización [`SDKSystemMessage`](#sdksystemmessage) actualmente lista esta herramienta como `Task` por compatibilidad con versiones anteriores.

```typescript theme={null}
type AgentOutput =
  | {
      status: "completed";
      agentId: string;
      agentType?: string;
      content: Array<{ type: "text"; text: string; citations?: unknown[] | null }>;
      resolvedModel?: string;
      modelsUsed?: 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: string | null;
        cache_creation: {
          ephemeral_1h_input_tokens: number;
          ephemeral_5m_input_tokens: number;
        } | null;
        inference_geo?: string | null;
        speed?: string | null;
        iterations?: unknown;
        output_tokens_details?: {
          thinking_tokens?: number | null;
        } | null;
        fallback_credit?: unknown;
      };
      toolStats?: {
        readCount: number;
        searchCount: number;
        bashCount: number;
        editFileCount: number;
        linesAdded: number;
        linesRemoved: number;
        otherToolCount: number;
        frameCount?: number;
      };
      prompt: string;
      worktreePath?: string;
      worktreeBranch?: string;
    }
  | {
      status: "async_launched";
      isAsync?: true;
      agentId: string;
      description: string;
      resolvedModel?: string;
      modelsUsed?: string[];
      prompt: string;
      outputFile: string;
      canReadOutputFile?: boolean;
    }
  | {
      status: "remote_launched";
      taskId: string;
      sessionUrl: string;
      description: string;
      prompt: string;
      outputFile: string;
    };
```

Devuelve el resultado del subagente. Se discrimina por el campo `status`: `"completed"` para tareas finalizadas, `"async_launched"` para tareas en segundo plano y `"remote_launched"` para tareas que Claude Code envió a una sesión en la nube, donde `sessionUrl` enlaza a esa sesión y `taskId` la identifica.

En la variante `completed`, `resolvedModel` indica el modelo con el que comenzó el subagente, que puede diferir de la entrada `model` solicitada cuando se aplica [`availableModels`](/docs/es/model-config#restrict-model-selection) u otra sobrescritura. Este campo requiere Claude Code v2.1.174 o posterior. En `async_launched`, indica el modelo en uso cuando la tarea pasó a segundo plano.

`modelsUsed` lista los modelos que usó el subagente, en orden. El campo solo está presente cuando hubo un cambio de modelo a mitad de la ejecución, y un modelo vuelve a aparecer cuando la ejecución regresó a él. En `async_launched`, la lista cubre los modelos usados antes de pasar a segundo plano. Tanto `modelsUsed` como el comportamiento de `resolvedModel` al pasar a segundo plano requieren Claude Code v2.1.212 o posterior.

Si Claude Code [conservó el worktree aislado del subagente](/docs/es/worktrees#isolate-subagents-with-worktrees), `worktreePath` en el resultado `completed` indica dónde encontrarlo. `worktreeBranch` es su rama, presente cuando Claude Code creó el worktree con git.

Claude Code completa `usage` y `totalTokens` a partir de la última solicitud a la API del subagente, no de toda la ejecución, por lo que `usage.service_tier` es la cadena del nivel de servicio que la API informó en esa solicitud. Cuando está presente, `usage.output_tokens_details.thinking_tokens` es la cantidad de tokens de salida de esa solicitud que fueron tokens de pensamiento. El campo `output_tokens_details` requiere TypeScript SDK v0.3.228 o posterior, que incluye Claude Code v2.1.228. El campo `fallback_credit` requiere TypeScript SDK v0.3.285 o posterior, que incluye Claude Code v2.1.285.

`usage.output_tokens_details` coincide en significado con [`Usage.output_tokens_details`](#usage), limitado a esa última solicitud, pero aquí todos sus niveles son opcionales. Protege tanto el objeto como el campo, por ejemplo `usage.output_tokens_details?.thinking_tokens ?? 0`, en lugar de leerlo directamente.

Antes de v2.1.207, el tipo publicado era más restringido. Omitía `worktreePath`, `worktreeBranch`, `citations`, `toolStats.frameCount` y los campos de uso `inference_geo`, `speed` e `iterations`, y tipaba `service_tier` como `"standard" | "priority" | "batch"`. Los campos que el tipo marca como opcionales pueden estar ausentes en resultados registrados por versiones anteriores.

<h3 id="askuserquestion-2">
  AskUserQuestion
</h3>

**Nombre de la herramienta:** `AskUserQuestion`

```typescript theme={null}
type AskUserQuestionOutput = {
  questions: Array<{
    question: string;
    header: string;
    options: Array<{ label: string; description: string; preview?: string }>;
    multiSelect: boolean;
  }>;
  answers: Record<string, string>;
  response?: string;
  annotations?: Record<string, { preview?: string; notes?: string }>;
  afkTimeoutMs?: number;
};
```

Devuelve las preguntas realizadas y las respuestas del usuario. `response` se establece cuando el usuario escribió una respuesta libre en lugar de responder las preguntas estructuradas; cuando está presente, Claude recibe "The user responded: …" en lugar de la lista de respuestas por pregunta.

<h3 id="bash-2">
  Bash
</h3>

**Nombre de la herramienta:** `Bash`

```typescript theme={null}
type BashOutput = {
  stdout: string;
  stderr: string;
  rawOutputPath?: string;
  interrupted: boolean;
  isImage?: boolean;
  backgroundTaskId?: string;
  backgroundedByUser?: boolean;
  timedOutAfterMs?: number;
  backgroundCwdHint?: string;
  backgroundEndsWithFinalResponse?: true;
  dangerouslyDisableSandbox?: boolean;
  returnCodeInterpretation?: string;
  noOutputExpected?: boolean;
  structuredContent?: unknown[];
  persistedOutputPath?: string;
  persistedOutputSize?: number;
  staleReadFileStateHint?: string;
  ghRateLimitHint?: string;
  gitOperation?: {
    commit?: { sha: string; kind: "committed" | "amended" | "cherry-picked"; branch?: string };
    push?: { branch: string };
    branch?: { ref: string; action: "merged" | "rebased" };
    pr?: {
      number: number;
      url?: string;
      action: "created" | "edited" | "merged" | "commented" | "closed" | "reopened" | "ready" | "draft" | "auto-merge-enabled" | "auto-merge-disabled";
    };
  };
};
```

Los campos `stdout`, `stderr` y `backgroundTaskId` contienen:

| Campo | Qué contiene |
| - | - |
| `stdout` | El stdout y el stderr del comando, combinados en un único flujo intercalado |
| `stderr` | Avisos que agrega la propia herramienta, como un restablecimiento del directorio de trabajo del shell, no el stderr del comando |
| `backgroundTaskId` | Presente para comandos en segundo plano |

`timedOutAfterMs` es el tiempo de espera en milisegundos, establecido cuando el comando alcanzó su tiempo de espera y pasó a segundo plano en lugar de iniciarse allí explícitamente. `backgroundCwdHint` se establece cuando el comando enviado a segundo plano contenía un builtin de cambio de directorio como `cd`, `pushd`, `popd` o `chdir`, e indica que el directorio de trabajo de la sesión no cambió. Ambos campos requieren Claude Code v2.1.210 o posterior.

Cuando un subagente que se ejecuta en primer plano es dueño de un comando en segundo plano, el comando [termina cuando termina la ejecución de ese subagente](/docs/es/tools-reference#when-a-background-command-stops). Claude Code establece `backgroundEndsWithFinalResponse` en `true` en esos comandos y omite el campo cuando el comando sobrevive al turno, como ocurre con los comandos iniciados por la conversación principal o por subagentes en segundo plano. El campo requiere Claude Code v2.1.227 o posterior.

Claude Code establece `gitOperation.commit.branch` en la rama indicada en la línea de resumen del commit de git, y lo omite para un commit hecho sobre un HEAD desacoplado. El campo requiere Agent SDK v0.3.227 o posterior. Claude Code informa un comando `gh pr reopen` como la acción de PR `reopened`, lo que requiere Agent SDK v0.3.234 o posterior.

<h3 id="monitor-2">
  Monitor
</h3>

**Nombre de la herramienta:** `Monitor`

```typescript theme={null}
type MonitorOutput = {
  taskId: string;
  timeoutMs: number;
  persistent?: boolean;
};
```

Devuelve el ID de la tarea en segundo plano del monitor en ejecución. Usa este ID con `TaskStop` para cancelar la vigilancia antes de tiempo.

<h3 id="edit-2">
  Edit
</h3>

**Nombre de la herramienta:** `Edit`

```typescript theme={null}
type FileEditOutput = {
  filePath: string;
  oldString: string;
  newString: string;
  originalFile: string | null;
  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;
    repository?: string | null;
  };
};
```

Devuelve el diff estructurado de la operación de edición.

<h3 id="read-2">
  Read
</h3>

**Nombre de la herramienta:** `Read`

```typescript theme={null}
type FileReadOutput =
  | {
      type: "text";
      file: {
        filePath: string;
        content: string;
        numLines: number;
        startLine: number;
        totalLines: number;
        /** True when a whole-file read was auto-paginated because it exceeded the token cap (the content is a partial first page). */
        truncatedByTokenCap?: boolean;
      };
    }
  | {
      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;
      };
      /** Document page number of the first extracted page; labels the page images in the tool_result content. */
      firstPage?: number;
      /** In-process only: the page-image bytes are delivered as image blocks in the tool_result content and aren't retained on the emitted tool_use_result, so this key is absent there. */
      pages?: {
        base64: string;
        mediaType: "image/jpeg" | "image/png" | "image/gif" | "image/webp";
        error?: string;
      }[];
    }
  | {
      type: "file_unchanged";
      file: {
        filePath: string;
      };
      /** Set when the dedup matched a startup-seeded entry (CLAUDE.md / nested memory) rather than a prior Read tool_result. */
      source?: "seeded";
    };
```

Devuelve el contenido del archivo en un formato adecuado para el tipo de archivo. Se discrimina por el campo `type`.

<h3 id="write-2">
  Write
</h3>

**Nombre de la herramienta:** `Write`

```typescript theme={null}
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;
    repository?: string | null;
  };
  userModified?: boolean;
};
```

Devuelve el resultado de la escritura con información de diff estructurado. Lo que contienen `originalFile` y `structuredPatch` depende de la escritura:

* Para un archivo recién creado, `originalFile` es null y `structuredPatch` está vacío
* Al sobrescribir, `originalFile` contiene el contenido anterior, excepto cuando ese contenido supera aproximadamente 10 MB: en ese caso Claude Code omite el diff y devuelve `originalFile` null y `structuredPatch` vacío
* `structuredPatch` también está vacío cuando la escritura no cambió nada o se agotó el tiempo de espera del diff

<h3 id="glob-2">
  Glob
</h3>

**Nombre de la herramienta:** `Glob`

```typescript theme={null}
type GlobOutput = {
  durationMs: number;
  numFiles: number;
  filenames: string[];
  truncated: boolean;
  totalMatches?: number;
  countIsComplete?: boolean;
};
```

Devuelve las rutas de archivo que coinciden con el patrón glob, ordenadas por fecha de modificación.

`totalMatches` y `countIsComplete` requieren Claude Code v2.1.191 o posterior. `totalMatches` informa la cantidad de archivos coincidentes antes del truncamiento. Cuando `countIsComplete` es false, `totalMatches` es un límite inferior porque la búsqueda subyacente truncó su propia salida.

<h3 id="grep-2">
  Grep
</h3>

**Nombre de la herramienta:** `Grep`

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

Devuelve los resultados de la búsqueda. La forma varía según `mode`: lista de archivos, contenido con coincidencias o recuento de coincidencias. En el modo `count`, `numFiles` y `numMatches` son totales sobre el conjunto completo de resultados, no sobre la porción paginada. Antes de v2.1.208, un `head_limit` u `offset` que truncaba las entradas listadas también truncaba esos totales.

`totalFiles` requiere Claude Code v2.1.208 o posterior e informa la cantidad total de resultados antes de la paginación con `head_limit` y `offset` en el modo `files_with_matches`. `totalLines` requiere Claude Code v2.1.210 o posterior e informa la cantidad total de líneas antes de la paginación en el modo `content`.

<h3 id="taskstop-2">
  TaskStop
</h3>

**Nombre de la herramienta:** `TaskStop`

```typescript theme={null}
type TaskStopOutput = {
  message: string;
  task_id: string;
  task_type: string;
  command?: string;
};
```

Devuelve una confirmación después de detener la tarea en segundo plano.

<h3 id="notebookedit-2">
  NotebookEdit
</h3>

**Nombre de la herramienta:** `NotebookEdit`

```typescript theme={null}
type NotebookEditOutput = {
  new_source: string;
  old_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;
};
```

Devuelve el resultado de la edición del notebook con el contenido original y actualizado del archivo.

<h3 id="webfetch-2">
  WebFetch
</h3>

**Nombre de la herramienta:** `WebFetch`

```typescript theme={null}
type WebFetchOutput = {
  bytes: number;
  code: number;
  codeText: string;
  result: string;
  durationMs: number;
  url: string;
  artifactRead?: {
    slug: string;
    ver?: string;
    seeded?: false;
  };
};
```

Devuelve el contenido obtenido con el estado HTTP y metadatos.

`artifactRead` es el registro propio de Claude Code de una lectura de artefacto, presente solo cuando Claude obtuvo un artefacto en el que la sesión puede publicar. Claude Code lo vuelve a leer cuando se reanuda una sesión para que una publicación posterior se base en la versión correcta; tu código no necesita actuar en consecuencia. `slug` nombra el artefacto, `ver` es la versión que la lectura dejó registrada y está ausente cuando no registró ninguna, y `seeded: false` marca una lectura cuyo código fuente completo no llegó a Claude. El campo `seeded` requiere Agent SDK v0.3.239 o posterior.

<h3 id="websearch-2">
  WebSearch
</h3>

**Nombre de la herramienta:** `WebSearch`

```typescript theme={null}
type WebSearchOutput = {
  query: string;
  results: Array<
    | {
        tool_use_id: string;
        content: Array<{ title: string; url: string }>;
      }
    | string
  >;
  durationSeconds: number;
  searchCount?: number;
};
```

Devuelve resultados de búsqueda de la web.

<h3 id="workflow-2">
  Workflow
</h3>

**Nombre de la herramienta:** `Workflow`

```typescript theme={null}
type WorkflowOutput = {
  status: "async_launched" | "remote_launched";
  taskId: string;
  taskType?: "local_workflow" | "remote_agent";
  workflowName?: string;
  runId?: string;
  summary?: string;
  transcriptDir?: string;
  scriptPath?: string;
  sessionUrl?: string; // set when the workflow launched as a cloud session
  warning?: string;
  error?: string;
};
```

Devuelve inmediatamente después de que la herramienta acepta la invocación. El resultado final llega más tarde como la finalización de una tarea. Revisa `error` antes de considerar que la ejecución comenzó: un script que no supera su verificación de sintaxis devuelve `status: "async_launched"` con `error` establecido, y nunca se ejecuta.

| Campo | Tipo | Descripción |
| - | - | - |
| `status` | `"async_launched" \| "remote_launched"` | La herramienta aceptó la invocación. `"async_launched"` para ejecuciones en proceso, `"remote_launched"` para ejecuciones enviadas a una sesión en la nube en lugar de ejecutarse en proceso |
| `taskId` | `string` | Identificador de la tarea en segundo plano de la ejecución |
| `taskType` | `"local_workflow" \| "remote_agent"` | Tipo de tarea de la tarea en segundo plano registrada, que coincide con la rama de `status` |
| `workflowName` | `string` | El `meta.name` del script del flujo de trabajo |
| `runId` | `string` | Identificador de la ejecución del flujo de trabajo que se pasa como `resumeFromRunId` en una invocación posterior. Ausente en ejecuciones `remote_launched`, donde la URL de la sesión en la nube es el identificador para reanudar |
| `summary` | `string` | Descripción de una línea de lo que hace el flujo de trabajo |
| `transcriptDir` | `string` | Directorio donde se escriben las transcripciones de los subagentes durante la ejecución |
| `scriptPath` | `string` | Ruta al script del flujo de trabajo persistido para esta ejecución. Edítalo y pásalo de vuelta como `scriptPath` para volver a ejecutar sin reenviar el script |
| `sessionUrl` | `string` | URL de la sesión en la nube, establecida cuando `status` es `"remote_launched"` |
| `warning` | `string` | Aviso no bloqueante, como que el estado local de git difiere de la rama enviada que clonará una sesión en la nube |
| `error` | `string` | Se establece cuando el script no supera su verificación de sintaxis. Cuando está presente, la ejecución no comenzó a pesar del estado de lanzamiento |

<h3 id="todowrite-2">
  TodoWrite
</h3>

**Nombre de la herramienta:** `TodoWrite`

```typescript theme={null}
type TodoWriteOutput = {
  oldTodos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
  newTodos: Array<{
    content: string;
    status: "pending" | "in_progress" | "completed";
    activeForm: string;
  }>;
};
```

Devuelve las listas de tareas anterior y actualizada.

<Note>
  Las siguientes herramientas están disponibles por defecto solo en modelos Claude 3.x, Opus 4 a través de 4.7, Sonnet 4 a través de 4.6 y Haiku 4.5. En todos los demás modelos, incluidos los ID de modelo que Claude Code no reconoce, no están disponibles a menos que opte por incluirlas:

  * `TodoWrite`
  * `TaskCreate`
  * `TaskGet`
  * `TaskUpdate`
  * `TaskList`

  Dondequiera que las herramientas estén disponibles, Claude Code proporciona las cuatro herramientas Task, o `TodoWrite` en su lugar cuando establece `CLAUDE_CODE_ENABLE_TASKS=0`.

  Este conjunto predeterminado se aplica en Claude Code v2.1.268 y posterior, que el TypeScript Agent SDK agrupa desde v0.3.268.

  Consulta [Disponibilidad de modelos](/docs/es/agent-sdk/todo-tracking#model-availability) para activarlo.
</Note>

<h3 id="taskcreate-2">
  TaskCreate
</h3>

**Nombre de la herramienta:** `TaskCreate`

```typescript theme={null}
type TaskCreateOutput = {
  task: {
    id: string;
    subject: string;
  };
};
```

Devuelve la tarea creada con su ID asignado.

<h3 id="taskupdate-2">
  TaskUpdate
</h3>

**Nombre de la herramienta:** `TaskUpdate`

```typescript theme={null}
type TaskUpdateOutput = {
  success: boolean;
  taskId: string;
  updatedFields: string[];
  error?: string;
  statusChange?: {
    from: string;
    to: string;
  };
};
```

Devuelve el resultado de la actualización, incluidos los campos que cambiaron.

<h3 id="taskget-2">
  TaskGet
</h3>

**Nombre de la herramienta:** `TaskGet`

```typescript theme={null}
type TaskGetOutput = {
  task: {
    id: string;
    subject: string;
    description: string;
    status: "pending" | "in_progress" | "completed";
    blocks: string[];
    blockedBy: string[];
  } | null;
};
```

Devuelve el registro completo de la tarea, o `null` cuando no se encuentra el ID.

<h3 id="tasklist-2">
  TaskList
</h3>

**Nombre de la herramienta:** `TaskList`

```typescript theme={null}
type TaskListOutput = {
  tasks: Array<{
    id: string;
    subject: string;
    status: "pending" | "in_progress" | "completed";
    owner?: string;
    blockedBy: string[];
  }>;
};
```

Devuelve una instantánea de todas las tareas de la lista actual.

<h3 id="exitplanmode-2">
  ExitPlanMode
</h3>

**Nombre de la herramienta:** `ExitPlanMode`

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

Devuelve el estado del plan después de salir del modo plan.

<h3 id="listmcpresources-2">
  ListMcpResources
</h3>

**Nombre de la herramienta:** `ListMcpResourcesTool`

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

Devuelve un array de los recursos MCP disponibles.

<h3 id="readmcpresource-2">
  ReadMcpResource
</h3>

**Nombre de la herramienta:** `ReadMcpResourceTool`

```typescript theme={null}
type ReadMcpResourceOutput = {
  contents: Array<{
    uri: string;
    mimeType?: string;
    text?: string;
    blobSavedTo?: string;
  }>;
  error?: string;
};
```

Devuelve el contenido del recurso MCP solicitado.

<h3 id="enterworktree-2">
  EnterWorktree
</h3>

**Nombre de la herramienta:** `EnterWorktree`

```typescript theme={null}
type EnterWorktreeOutput = {
  worktreePath: string;
  worktreeBranch?: string;
  message: string;
};
```

Devuelve información sobre el worktree de git.

<h3 id="exitworktree-2">
  ExitWorktree
</h3>

**Nombre de la herramienta:** `ExitWorktree`

```typescript theme={null}
type ExitWorktreeOutput = {
  action: "keep" | "remove";
  originalCwd: string;
  worktreePath: string;
  worktreeBranch?: string;
  tmuxSessionName?: string;
  discardedFiles?: number;
  discardedCommits?: number;
  message: string;
};
```

Devuelve la acción realizada y los detalles del worktree del que se salió.

<h3 id="enterplanmode-2">
  EnterPlanMode
</h3>

**Nombre de la herramienta:** `EnterPlanMode`

```typescript theme={null}
type EnterPlanModeOutput = {
  message: string;
};
```

Devuelve una confirmación de que se entró en modo plan.

<h3 id="croncreate-2">
  CronCreate
</h3>

**Nombre de la herramienta:** `CronCreate`

```typescript theme={null}
type CronCreateOutput = {
  id: string;
  humanSchedule: string;
  recurring: boolean;
  durable?: boolean; // true when persisted to .claude/scheduled_tasks.json; false when session-only
};
```

Devuelve el ID del trabajo y una descripción legible de la programación.

<h3 id="crondelete-2">
  CronDelete
</h3>

**Nombre de la herramienta:** `CronDelete`

```typescript theme={null}
type CronDeleteOutput = {
  id: string;
};
```

Devuelve el ID del trabajo eliminado.

<h3 id="cronlist-2">
  CronList
</h3>

**Nombre de la herramienta:** `CronList`

```typescript theme={null}
type CronListOutput = {
  jobs: {
    id: string;
    cron: string;
    humanSchedule: string;
    prompt: string;
    recurring?: boolean;
    durable?: boolean;
  }[];
};
```

Devuelve los trabajos cron programados: los trabajos duraderos de `.claude/scheduled_tasks.json` y los trabajos exclusivos de la sesión actual. Un trabajo exclusivo de la sesión incluye `durable: false`; los trabajos leídos del disco omiten el campo.

<h3 id="schedulewakeup-2">
  ScheduleWakeup
</h3>

**Nombre de la herramienta:** `ScheduleWakeup`

```typescript theme={null}
type ScheduleWakeupOutput = {
  scheduledFor: number;
  clampedDelaySeconds: number;
  wasClamped: boolean;
  stopped?: boolean;
  cancelledWakeups?: number;
};
```

Devuelve cuándo se activará el despertar como una marca de tiempo en milisegundos desde epoch, el retraso realmente usado y si el retraso solicitado se ajustó a los límites. El campo `stopped` es `true` cuando la llamada finalizó el bucle con `stop: true`. Requiere Claude Code v2.1.202 o posterior. El campo `cancelledWakeups` cuenta cuántos despertares pendientes canceló una llamada con `stop: true`. Un valor de 0 significa que no había nada pendiente, y un cron recurrente de `/loop` no se cancela con `stop: true`. Requiere Claude Code v2.1.206 o posterior.

<h3 id="remotetrigger-2">
  RemoteTrigger
</h3>

**Nombre de la herramienta:** `RemoteTrigger`

```typescript theme={null}
type RemoteTriggerOutput = {
  status: number;
  json: string;
  summary?: string;
};
```

Devuelve el estado y el cuerpo de la respuesta de la API para la operación del disparador.

<h3 id="pushnotification-2">
  PushNotification
</h3>

**Nombre de la herramienta:** `PushNotification`

```typescript theme={null}
type PushNotificationOutput = {
  message: string;
  pushSent?: boolean;
  localSent?: boolean;
  disabledReason?: "config_off" | "user_present" | "no_transport";
  sentAt?: string;
};
```

Devuelve los detalles de la entrega, incluido si se envió una notificación push o local y por qué se omitió la entrega.

<h3 id="reportfindings-2">
  ReportFindings
</h3>

**Nombre de la herramienta:** `ReportFindings`

```typescript theme={null}
type ReportFindingsOutput = {
  count: number;
  level?: "low" | "medium" | "high" | "xhigh" | "max";
  findings: Array<{
    file: string;
    line?: number;
    summary: string;
    failure_scenario: string;
    short_summary?: string;
    category?: string;
    verdict?: "CONFIRMED" | "PLAUSIBLE";
    outcome?: "fixed" | "skipped" | "no_change_needed";
  }>;
};
```

Devuelve la cantidad de hallazgos informados, el nivel de esfuerzo con el que se ejecutó la revisión y los hallazgos devueltos para el cuerpo del resultado. Requiere Claude Code v2.1.196 o posterior. El campo devuelto `short_summary` requiere Claude Code v2.1.212 o posterior.

<h3 id="artifact-2">
  Artifact
</h3>

**Nombre de la herramienta:** `Artifact`

```typescript theme={null}
type ArtifactOutput =
  | {
      url: string;
      path: string;
      title?: string;
      version?: string;
      capabilities?: unknown;
      stored?: {
        contract: string;
        capabilities?: Record<string, unknown>;
      };
      warnings?: string[];
      contract?: string;
      updated?: boolean;
      liveSubscription?: string;
    }
  | {
      artifacts: Array<{
        title: string;
        url: string;
        updatedAt?: string;
        rel?: "mine" | "shared";
      }>;
      truncated?: boolean;
      scope?: "shared" | "all";
    };
```

Para la acción de publicación, devuelve la `url` de la página publicada y la `path` local que se publicó, con `updated` establecido en true cuando la publicación volvió a desplegar un artefacto existente, y `warnings` con cualquier advertencia del momento de la publicación. La acción de listado devuelve en cambio las filas de `artifacts`, con `truncated` establecido cuando existen más artefactos que el límite solicitado. En los listados cuyo alcance no es `"mine"`, cada fila incluye `rel`, que indica si el usuario es dueño del artefacto o si se compartió con él, y el `scope` de la salida registra qué alcance no predeterminado produjo el listado; ambos están ausentes en los listados predeterminados.

<h3 id="projects-2">
  Projects
</h3>

**Nombre de la herramienta:** `Projects`

```typescript theme={null}
type ProjectsOutput =
  | {
      method: "project_info";
      notice?: string;
      name: string;
      description: string;
      instructions: string;
      docs: Array<{ path: string; created_at: string | null }>;
      files?: Array<{
        path: string;
        file_kind: string;
        created_at: string | null;
      }>;
      sync_sources?: Array<{
        type: string | null;
        config: Record<string, unknown>;
      }>;
      knowledge: {
        knowledge_size: number;
        max_knowledge_size: number;
      };
    }
  | {
      method: "project_read";
      notice?: string;
      path: string;
      file_kind?: string;
      content?: string;
      local_file?: string;
      created_at: string | null;
    }
  | {
      method: "project_search";
      notice?: string;
      rag: boolean;
      hits?: Array<{ name?: string; doc_uuid?: string; text?: string }>;
      docs?: string[];
    }
  | {
      method: "project_write";
      notice?: string;
      path: string;
      doc_uuid: string;
      replaced: boolean;
      present_to_user?: boolean;
      local_path?: string;
    }
  | {
      method: "project_delete";
      notice?: string;
      path: string;
      deleted: boolean;
    };
```

Se discrimina por el campo `method`, reflejando la entrada. `project_read` devuelve los documentos de texto pequeños en línea en `content` y, en cambio, escribe los documentos más grandes en una ruta `local_file`; `project_search` devuelve `hits` de RAG con `rag: true` cuando el índice del proyecto está disponible y, en caso contrario, recurre a una lista de rutas `docs`.

<h3 id="readmcpresourcedir-2">
  ReadMcpResourceDir
</h3>

**Nombre de la herramienta:** `ReadMcpResourceDirTool`

```typescript theme={null}
type ReadMcpResourceDirOutput = {
  resources: Array<{
    uri: string;
    name: string;
    mimeType?: string;
  }>;
  error?: string;
};
```

Devuelve los hijos directos del recurso de directorio. Los subdirectorios aparecen con mimeType `"inode/directory"`; `error` contiene un mensaje legible cuando el servidor no pudo listar el directorio.

<h3 id="refreshmcptools-2">
  RefreshMcpTools
</h3>

**Nombre de la herramienta:** `RefreshMcpTools`

```typescript theme={null}
type RefreshMcpToolsOutput = Array<{
  server: string;
  status: "refreshed" | "error" | "not_connected";
  toolCount?: number; // tools now available from this server
  added?: string[]; // tool names this refresh added
  removed?: string[]; // tool names this refresh removed
  error?: string; // why the refresh failed or the server was unavailable
}>;
```

Devuelve una entrada por servidor: `refreshed` significa que se aplicó la lista de herramientas consultada de nuevo, `error` significa que la nueva consulta falló y se conservó el conjunto de herramientas anterior, y `not_connected` significa que el servidor no tiene una conexión activa para consultar.

<h3 id="showonboardingrolepicker-2">
  ShowOnboardingRolePicker
</h3>

**Nombre de la herramienta:** `ShowOnboardingRolePicker`

```typescript theme={null}
type ShowOnboardingRolePickerOutput = {
  role?: string;
  dismissed?: boolean;
};
```

Devuelve la selección del usuario: `role` cuando eligió un chip de rol o escribió uno, y `dismissed: true` cuando cerró el selector. Un objeto vacío significa que el usuario aprobó la llamada sin elegir un rol.

<h3 id="mcpoutput">
  McpOutput
</h3>

**Nombre de la herramienta:** nombres dinámicos de herramientas MCP con la forma `mcp__<server>__<tool>`

```typescript theme={null}
type McpOutput =
  | string
  | {
      type: string;
      [k: string]: unknown;
    }[]
  | {
      [k: string]: unknown;
    };
```

Los resultados de las herramientas MCP se devuelven como una cadena o un array de bloques de contenido, según el servidor. La rama final de objeto simple en el tipo exportado es un residuo de la generación del esquema. Para un resultado que además incluye `structuredContent` o enlaces a recursos, consulta [`tool_use_result`](#sdkusermessage), que contiene este valor en su miembro `content`. En tiempo de ejecución, el valor también puede ser `undefined`, aunque el tipo exportado no lo modela.

<h2 id="permission-types">
  Tipos de Permiso
</h2>

<h3 id="permissionupdate">
  `PermissionUpdate`
</h3>

Operaciones para actualizar permisos.

```typescript theme={null}
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;
    };
```

<h3 id="permissionbehavior">
  `PermissionBehavior`
</h3>

```typescript theme={null}
type PermissionBehavior = "allow" | "deny" | "ask";
```

<h3 id="permissionupdatedestination">
  `PermissionUpdateDestination`
</h3>

```typescript theme={null}
type PermissionUpdateDestination =
  | "userSettings" // Configuración global del usuario
  | "projectSettings" // Configuración del proyecto por directorio
  | "localSettings" // Configuración local del proyecto
  | "session" // Solo sesión actual
  | "cliArg"; // Argumento CLI
```

<h3 id="permissionrulevalue">
  `PermissionRuleValue`
</h3>

```typescript theme={null}
type PermissionRuleValue = {
  toolName: string;
  ruleContent?: string;
};
```

<h2 id="other-types">
  Otros tipos
</h2>

<h3 id="apikeysource">
  `ApiKeySource`
</h3>

De dónde provino la clave de API para las solicitudes de la sesión, reportada como `apiKeySource` en el mensaje de inicialización [`SDKSystemMessage`](#sdksystemmessage).

```typescript theme={null}
type ApiKeySource =
  | "ANTHROPIC_API_KEY"
  | "apiKeyHelper"
  | "/login managed key"
  | "none"
  | "user"
  | "project"
  | "org"
  | "temporary"
  | "oauth";
```

Claude Code reporta uno de cuatro valores:

| Valor | Clave en uso |
| - | - |
| `ANTHROPIC_API_KEY` | La clave en la variable de entorno `ANTHROPIC_API_KEY` |
| `apiKeyHelper` | La clave devuelta por tu comando [`apiKeyHelper`](/docs/es/settings-reference#apikeyhelper) |
| `/login managed key` | La clave que Claude Code almacenó cuando iniciaste sesión con una [cuenta de Claude Console](/docs/es/authentication#claude-console-authentication) |
| `none` | Sin clave de API. La sesión se autentica de otra manera, como un inicio de sesión en claude.ai, un token portador o un proveedor de nube |

Agent SDK v0.3.234 y posterior enumeran estos cuatro valores en el tipo. El tipo también mantiene `user`, `project`, `org`, `temporary` y `oauth` para que el código más antiguo siga compilándose, y Claude Code no los reporta.

<h3 id="sdkbeta">
  `SdkBeta`
</h3>

Características beta disponibles que se pueden habilitar a través de la opción `betas`. Consulta [Encabezados beta](https://platform.claude.com/docs/en/api/beta-headers) para más información.

```typescript theme={null}
type SdkBeta = "context-1m-2025-08-07";
```

<Warning>
  En la Claude API, la beta `context-1m-2025-08-07` está retirada para Claude Sonnet 4.5 y Claude Sonnet 4. Si todavía la pasas con cualquiera de esos modelos, las solicitudes que excedan la ventana de contexto estándar de 200K tokens devuelven un error, así que quítala de `betas`. Para ejecutar una sesión con una ventana de contexto de 1M tokens, establece `model` en un modelo que [se ejecute con la ventana de 1M de forma predeterminada](/docs/es/model-config#extended-context), como `claude-sonnet-5-5` o `claude-opus-5-5`. Para un modelo que alcanza 1M solo a través de su variante `[1m]`, agrega el sufijo al ID del modelo, como en `claude-opus-4-6[1m]`.
</Warning>

<h3 id="slashcommand">
  `SlashCommand`
</h3>

Información sobre un comando disponible.

```typescript theme={null}
type SlashCommand = {
  name: string;
  description: string;
  argumentHint: string;
  aliases?: string[];
  builtin?: boolean;
};
```

`builtin` es `true` en una fila cuando el comando es propio de Claude Code y escribir `/name` lo ejecuta. Está ausente para un comando definido por un usuario, proyecto, plugin o servidor MCP, y para un comando incluido que uno de esos [reemplaza por nombre](/docs/es/skills#resolve-skills-that-share-a-name). Requiere Agent SDK v0.3.277 o posterior.

<h3 id="modelinfo">
  `ModelInfo`
</h3>

Información sobre un modelo disponible.

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

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `value` | `string` | Identificador de modelo para pasar en llamadas a la API |
| `resolvedModel` | `string \| undefined` | El ID de modelo al que se resuelve el `value` de esta entrada, como `claude-sonnet-5-5` para la entrada del alias `sonnet`. Requiere Claude Code v2.1.197 o posterior. |
| `displayName` | `string` | Nombre de visualización legible para humanos |
| `description` | `string` | Descripción de las capacidades del modelo |
| `supportsEffort` | `boolean \| undefined` | Si este modelo admite niveles de esfuerzo |
| `supportedEffortLevels` | `("low" \| "medium" \| "high" \| "xhigh" \| "max")[] \| undefined` | Niveles de esfuerzo que este modelo acepta |
| `supportsAdaptiveThinking` | `boolean \| undefined` | Si este modelo admite pensamiento adaptativo, donde Claude decide cuándo y cuánto pensar |
| `supportsFastMode` | `boolean \| undefined` | Si este modelo admite modo rápido |
| `supportsAutoMode` | `boolean \| undefined` | Si este modelo admite modo automático |

<h3 id="agentinfo">
  `AgentInfo`
</h3>

Información sobre un subagente disponible que se puede invocar a través de la herramienta Agent.

```typescript theme={null}
type AgentInfo = {
  name: string;
  description: string;
  model?: string;
};
```

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `name` | `string` | Identificador de tipo de agente (por ejemplo, `"Explore"`, `"general-purpose"`) |
| `description` | `string` | Descripción de cuándo usar este agente |
| `model` | `string \| undefined` | Modelo que usa este agente: un alias o ID de modelo, o `'inherit'` para el modelo del padre. Cuando es `undefined`, Claude Code elige el modelo en el [orden de modelo de subagente](/docs/es/sub-agents#choose-a-model) |

<h3 id="mcpserverprovenance">
  `McpServerProvenance`
</h3>

El servidor MCP que sirve una herramienta `mcp__*`, y de dónde provino la definición de ese servidor. Las entradas de hook [`PreToolUse`](#pretoolusehookinput), `PostToolUse`, `PostToolUseFailure`, `PermissionRequest` y `PermissionDenied` la llevan como `mcp_server`, y las opciones [`CanUseTool`](#canusetool) la llevan como `mcpServer`. Ambas la omiten para herramientas que no provienen de un servidor MCP.

```typescript theme={null}
type McpServerProvenance = {
  name: string;
  source: string;
};
```

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `name` | `string` | El nombre bajo el cual está registrado el servidor, el mismo valor que [`mcpServerStatus()`](#query-object) reporta para él |
| `source` | `string` | De dónde provino la definición del servidor: `sdk`, `plugin` o un alcance de configuración |

`source` toma uno de los siguientes valores. El conjunto está abierto, así que trata un valor que no reconozcas como una fuente configurada, nunca como `sdk`:

* **`sdk`**: un servidor en proceso que tu aplicación registró. Solo la aplicación host del SDK puede registrar uno, así que un servidor configurado nunca reporta `sdk`, sea cual sea su nombre.
* **`plugin`**: un servidor que proporciona un [plugin](/docs/es/agent-sdk/plugins). Su `name` es la forma con alcance `plugin:<plugin-name>:<server-name>` descrita en [servidores MCP proporcionados por plugins](/docs/es/mcp#plugin-provided-mcp-servers).
* **Un alcance de configuración**: `user`, `project`, `local`, `dynamic`, `managed`, `enterprise`, `claudeai` o `agent`. Un servidor de `.mcp.json` reporta `project`, y [alcances de instalación de MCP](/docs/es/mcp#mcp-installation-scopes) define `local`, `project` y `user`. Los servidores que tu aplicación pasa en la [opción `mcpServers`](#options), salvo los servidores SDK en proceso, reportan `dynamic`.

Basa las decisiones de confianza en `source`, no en `name` ni en el prefijo de nombre de herramienta `mcp__<server>__`. Para cualquier fuente que no sea `sdk`, `name` es texto no confiable: escápalo antes de mostrarlo.

`McpServerProvenance` y los campos que la llevan requieren Agent SDK v0.3.274 o posterior.

<h3 id="mcpserverstatus">
  `McpServerStatus`
</h3>

Estado de un servidor MCP conectado.

```typescript theme={null}
type McpServerStatus = {
  name: string;
  status: "connected" | "failed" | "needs-auth" | "pending" | "disabled";
  serverInfo?: {
    name: string;
    version: string;
  };
  error?: string;
  config?: McpServerStatusConfig;
  scope?: string;
  source?: string;
  tools?: {
    name: string;
    description?: string;
    annotations?: {
      readOnly?: boolean;
      destructive?: boolean;
      openWorld?: boolean;
    };
    _meta?: Record<string, unknown>;
  }[];
};
```

`source` indica de dónde provino la definición del servidor, con los mismos valores y regla de confianza que el `source` de [`McpServerProvenance`](#mcpserverprovenance). El campo requiere Agent SDK v0.3.274 o posterior y está ausente en versiones anteriores.

`_meta` en una entrada de `tools` lleva los miembros de MCP Apps del `_meta` de esa herramienta, para que tu aplicación pueda encontrar el recurso `ui://` que debe renderizar con [`readMcpResource()`](#query-object). Claude Code transmite el objeto `ui` y la cadena plana obsoleta `ui/resourceUri`, y retiene todas las demás claves. Dentro de `ui`, `resourceUri` es una cadena `ui://` y `visibility` un array de `"model"` y `"app"` cuando el servidor los establece, y cualquier otro miembro pasa sin cambios. Claude Code descarta cualquiera de las dos claves cuando el valor está mal formado, y omite `_meta` de una herramienta que no declara ninguna. El campo está presente solo cuando las [`capabilities`](#sdksystemmessage) del mensaje de inicialización incluyen `mcp_tool_ui_meta_v1`, y requiere TypeScript Agent SDK v0.3.280 o posterior.

<h3 id="mcpserverstatusconfig">
  `McpServerStatusConfig`
</h3>

La configuración de un servidor MCP tal como la reporta `mcpServerStatus()`. Esta es la unión de todos los tipos de transporte de servidor MCP.

```typescript theme={null}
type McpServerStatusConfig =
  | McpStdioServerConfig
  | McpSSEServerConfig
  | McpHttpServerConfig
  | McpSdkServerConfig
  | McpClaudeAIProxyServerConfig;
```

Consulta [`McpServerConfig`](#mcpserverconfig) para ver detalles sobre cada tipo de transporte.

<h3 id="accountinfo">
  `AccountInfo`
</h3>

Información de cuenta del usuario autenticado.

```typescript theme={null}
type AccountInfo = {
  email?: string;
  organization?: string;
  subscriptionType?: string;
  tokenSource?: string;
  apiKeySource?: string;
};
```

<h3 id="modelusage">
  `ModelUsage`
</h3>

Estadísticas de uso por modelo devueltas en mensajes de resultado. El valor `costUSD` es una estimación del lado del cliente. Consulta [Rastrear costo y uso](/docs/es/agent-sdk/cost-tracking) para ver advertencias sobre facturación.

```typescript theme={null}
type ModelUsage = {
  inputTokens: number;
  outputTokens: number;
  thinkingTokens?: number;
  cacheReadInputTokens: number;
  cacheCreationInputTokens: number;
  webSearchRequests: number;
  costUSD: number;
  contextWindow: number;
  maxOutputTokens: number;
  canonicalModel?: string;
  provider?: string;
  costBasis?: 'list' | 'managed' | 'unknown';
};
```

`thinkingTokens` cuenta los tokens de pensamiento que generó este modelo. `outputTokens` ya los incluye, así que no sumes los dos. El campo está ausente hasta que un turno se ejecuta en una versión de Claude Code que lo registra, por lo que una sesión reanudada que comenzó en una versión anterior reporta un recuento parcial. `thinkingTokens` requiere Agent SDK v0.3.257 o posterior.

Los campos `canonicalModel` y `provider` requieren Claude Code v2.1.218 o posterior. `canonicalModel` es el ID de modelo canónico que usa la búsqueda de precios; puede diferir de la cadena de modelo sin procesar que sirve de clave a la entrada, por ejemplo cuando esa cadena es un ID específico del proveedor o un alias.

`provider` nombra el backend de API que sirvió el modelo, como `firstParty`, `bedrock`, `vertex`, `foundry`, `anthropicAws`, `mantle` o `gateway`.

`costBasis` nombra la tabla de precios que fijó el precio de la solicitud más reciente del modelo: `list` para precio de lista, `managed` para una tabla [`modelPricing`](/docs/es/settings-reference#modelpricing), o `unknown` cuando ninguna coincidió con el ID del modelo. El campo requiere Claude Code v2.1.246 o posterior.

<h3 id="configscope">
  `ConfigScope`
</h3>

```typescript theme={null}
type ConfigScope = "local" | "user" | "project";
```

<h3 id="nonnullableusage">
  `NonNullableUsage`
</h3>

Una versión de [`Usage`](#usage) con todos los campos anulables convertidos en no anulables, excepto `fallback_credit`, que todavía puede ser `null`.

```typescript theme={null}
type NonNullableUsage = {
  [K in keyof Usage]: K extends "fallback_credit"
    ? Usage[K]
    : NonNullable<Usage[K]>;
};
```

<h3 id="usage">
  `Usage`
</h3>

Estadísticas de uso de tokens. Este es el tipo `BetaUsage` de `@anthropic-ai/sdk`.

```typescript theme={null}
type Usage = {
  input_tokens: number;
  output_tokens: number;
  cache_creation_input_tokens: number | null;
  cache_read_input_tokens: number | null;
  cache_creation: {
    ephemeral_5m_input_tokens: number;
    ephemeral_1h_input_tokens: number;
  } | null;
  server_tool_use: BetaServerToolUsage | null;
  service_tier: "standard" | "priority" | "batch" | null;
  speed: "standard" | "fast" | null;
  inference_geo: string | null;
  iterations: BetaIterationsUsage | null;
  output_tokens_details: BetaOutputTokensDetails | null;
  fallback_credit: BetaFallbackCreditUsage | null;
};
```

`BetaServerToolUsage`, `BetaIterationsUsage`, `BetaOutputTokensDetails` y `BetaFallbackCreditUsage` se definen en `@anthropic-ai/sdk`.

`output_tokens_details` desglosa la salida facturada por categoría. Actualmente lleva un campo, `thinking_tokens: number`, que cuenta los tokens de salida que el modelo generó como razonamiento interno, incluidos los delimitadores de bloque de pensamiento. El campo `output_tokens_details` requiere TypeScript SDK v0.3.228 o posterior, que incluye Claude Code v2.1.228.

* **Facturación**: lee el desglose para observabilidad, no para facturación. `output_tokens` sigue siendo el total de referencia, y `output_tokens - thinking_tokens` aproxima la salida sin razonamiento.
* **Qué cubre el recuento**: el razonamiento sin procesar que produjo el modelo, que puede ser más largo que el texto de pensamiento devuelto en el cuerpo de la respuesta. La API lo calcula volviendo a tokenizar ese texto sin procesar, por lo que puede diferir en algunos tokens del recuento exacto de generación del modelo.
* **Streaming**: en los mensajes de asistente enviados en streaming, este desglose, al igual que `output_tokens`, es un marcador de posición de `message_start` y no lleva un recuento real, así que léelo del `usage` del mensaje de resultado como se describe en [Leer tokens de salida del mensaje de resultado](/docs/es/agent-sdk/cost-tracking#read-output-tokens-from-the-result-message). En el mensaje de resultado, `thinking_tokens` vale `0` cuando el modelo o el proveedor no reporta desglose.
* **Casos `null`**: `output_tokens_details` en sí es `null` en mensajes de asistente que Claude Code sintetiza, como los mensajes de error de la API.

Que `Usage` lleve `fallback_credit` depende de tu `@anthropic-ai/sdk` instalado, que lo agregó en 0.115.0.

<h3 id="calltoolresult">
  `CallToolResult`
</h3>

Tipo de resultado de herramienta MCP (de `@modelcontextprotocol/sdk/types.js`). `structuredContent` es un objeto JSON que se puede devolver junto con `content`, incluidos bloques de imagen. Consulta [Devolver datos estructurados](/docs/es/agent-sdk/custom-tools#return-structured-data).

```typescript theme={null}
type CallToolResult = {
  content: Array<{
    type: "text" | "image" | "audio" | "resource" | "resource_link";
    // Los campos adicionales varían por tipo
  }>;
  structuredContent?: Record<string, unknown>;
  isError?: boolean;
};
```

<h3 id="sdkmcpresourcelink">
  `SDKMcpResourceLink`
</h3>

Un archivo que una herramienta MCP devolvió por referencia. Claude Code crea cada entrada a partir de un bloque `resource_link` en el resultado de la herramienta y entrega la lista como `resourceLinks` en [`SDKUserMessage.tool_use_result`](#sdkusermessage), o como `resource_links` en [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) cuando la llamada terminó en segundo plano. Requiere Agent SDK v0.3.257 o posterior.

```typescript theme={null}
type SDKMcpResourceLink = {
  uri: string;
  name: string;
  title?: string;
  description?: string;
  mimeType?: string;
  size?: number;
  annotations?: Record<string, unknown>;
};
```

Claude Code descarta un bloque cuyo `uri` o `name` no sea una cadena, y omite un campo opcional cuyo valor no sea del tipo indicado.

| Campo | Tipo | Descripción |
| :- | :- | :- |
| `uri` | `string` | URI del recurso, tal como lo devolvió el servidor |
| `name` | `string` | Nombre que el servidor le dio al recurso |
| `title` | `string \| undefined` | Título de visualización, cuando el servidor estableció uno |
| `description` | `string \| undefined` | Descripción, cuando el servidor estableció una |
| `mimeType` | `string \| undefined` | Tipo MIME, cuando el servidor estableció uno |
| `size` | `number \| undefined` | Tamaño en bytes, cuando el servidor estableció uno |
| `annotations` | `Record<string, unknown> \| undefined` | El objeto de anotaciones MCP del bloque, cuando el servidor estableció uno |

<h3 id="thinkingconfig">
  `ThinkingConfig`
</h3>

Controla el comportamiento de pensamiento/razonamiento de Claude. Tiene precedencia sobre el obsoleto `maxThinkingTokens`.

```typescript theme={null}
type ThinkingDisplay = "summarized" | "omitted";

type ThinkingConfig =
  | { type: "adaptive"; display?: ThinkingDisplay } // El modelo determina cuándo y cuánto razonar (Opus 4.6+)
  | { type: "enabled"; budgetTokens?: number; display?: ThinkingDisplay } // Presupuesto fijo de tokens de pensamiento
  | { type: "disabled" }; // Sin pensamiento extendido
```

El campo opcional `display` controla si el texto de pensamiento se devuelve `"summarized"` u `"omitted"`. En Claude Opus 4.7 y posterior, el valor predeterminado de la API es `"omitted"`, así que establece `"summarized"` para recibir contenido de pensamiento en bloques `thinking`. Claude Code no envía `display` a Amazon Bedrock ni a Agent Platform de Google Cloud, por lo que en esos proveedores Opus 4.7 y posterior devuelven bloques `thinking` vacíos incluso cuando estableces `display` en `"summarized"`.

<h3 id="spawnedprocess">
  `SpawnedProcess`
</h3>

Interfaz para la creación personalizada de procesos (se usa con la opción `spawnClaudeCodeProcess`). `ChildProcess` ya satisface esta interfaz.

```typescript theme={null}
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;
}
```

<h3 id="spawnoptions">
  `SpawnOptions`
</h3>

Opciones que se pasan a la función de creación personalizada.

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

<Note>
  El campo `signal` le indica a tu función de creación cuándo desmontar el proceso. Pásalo como la opción `signal` al `spawn()` de Node, o pásalo a tu controlador de desmontaje de VM o contenedor.

  Esta señal no se activa en el instante en que [`Options.abortController`](#options) aborta. El SDK primero cierra el stdin del proceso y espera unos dos segundos para que la CLI se cierre limpiamente, y luego aborta esta señal. Para reaccionar en cambio en el momento en que el llamador aborta, escucha tu propio `Options.abortController.signal`, al que tu función de creación puede hacer referencia desde su alcance envolvente.
</Note>

<h3 id="mcpsetserversresult">
  `McpSetServersResult`
</h3>

Resultado de una operación `setMcpServers()`.

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

Cuando llamas a `setMcpServers()`, Claude Code aplica estas reglas:

* **Servidores que la llamada no nombra**: Claude Code mantiene en ejecución los servidores proporcionados por plugins. Requiere Agent SDK v0.3.210 o posterior.
* **Servidores que la llamada nombra**: salvo los servidores integrados que la CLI inició al arrancar, Claude Code reemplaza un servidor en ejecución solo cuando su configuración difiere de la que pasaste.
* **Servidores integrados que la CLI inició al arrancar**: si la llamada nombra uno, Claude Code descarta esa entrada y la reporta en `errors`.

La promesa se resuelve después de que los servidores stdio, HTTP y SSE recién agregados se conecten o fallen, por lo que las herramientas de los servidores que se conectaron están disponibles en el siguiente turno.

`added` enumera los servidores que Claude Code agregó o reemplazó, se hayan conectado o no. Un servidor que no logró conectarse aparece tanto en `added` como en `errors`, con el texto del error en `errors` y una fila `failed` en [`mcpServerStatus()`](#methods). Antes de Claude Code v2.1.257, un servidor cuyo intento de conexión lanzó una excepción se reportaba solo en `errors`.

<h3 id="rewindfilesresult">
  `RewindFilesResult`
</h3>

Resultado de una operación `rewindFiles()`.

```typescript theme={null}
type RewindFilesResult = {
  canRewind: boolean;
  error?: string;
  filesChanged?: string[];
  insertions?: number;
  deletions?: number;
  skippedLinks?: number;
};
```

`skippedLinks` cuenta las rutas rastreadas que el rebobinado se negó a restaurar o eliminar por seguridad de enlaces: un enlace simbólico, un enlace duro u otro archivo no regular en la ruta rastreada, un directorio padre que ya no se resuelve a donde apuntaba cuando se tomó el checkpoint, o una copia de seguridad que no se pudo leer de forma segura. El campo requiere Claude Code v2.1.216 o posterior. Una llamada de vista previa con `rewindFiles(userMessageId, { dryRun: true })` nunca lo establece.

<h3 id="sdkstatusmessage">
  `SDKStatusMessage`
</h3>

Mensaje de actualización de estado (por ejemplo, compactación).

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

<h3 id="sdktasknotificationmessage">
  `SDKTaskNotificationMessage`
</h3>

Notificación cuando una tarea en segundo plano se completa, falla o se detiene. Las tareas en segundo plano incluyen comandos Bash con `run_in_background`, vigilancias de [Monitor](#monitor) y subagentes en segundo plano. Para el campo `ambient`, consulta [`SDKTaskStartedMessage`](#sdktaskstartedmessage), que lo define junto con su requisito de versión.

```typescript theme={null}
type SDKTaskNotificationMessage = {
  type: "system";
  subtype: "task_notification";
  task_id: string;
  tool_use_id?: string;
  status: "completed" | "failed" | "stopped";
  output_file: string;
  summary: string;
  ambient?: boolean;
  usage?: {
    total_tokens: number;
    tool_uses: number;
    duration_ms: number;
  };
  resource_links?: SDKMcpResourceLink[];
  uuid: UUID;
  session_id: string;
};
```

Cuando Claude Code [mueve una llamada a herramienta MCP larga a segundo plano](/docs/es/mcp#automatic-backgrounding-of-long-tool-calls), el bloque `tool_result` de esa llamada contiene solo un marcador de posición y el resultado real de la llamada llega en esta notificación. Asocia la notificación con la llamada mediante `tool_use_id`. En una notificación `completed`, `resource_links` enumera los archivos que la herramienta devolvió por referencia como entradas [`SDKMcpResourceLink`](#sdkmcpresourcelink), con los mismos límites de 50 enlaces y 64 KiB que [`tool_use_result.resourceLinks`](#sdkusermessage). Claude Code omite `resource_links` cuando el resultado no tenía enlaces y en notificaciones de tareas que no son llamadas a herramientas MCP. `resource_links` requiere Agent SDK v0.3.257 o posterior.

Claude Code antepone un aviso a cada notificación de tarea que envía al modelo, excepto en las entregas marcadas con el [subtipo `scheduled-trigger`](#task-notification-subkinds), que en su lugar llevan un encuadre de tarea asignada. El aviso indica que no ha habido ninguna entrada humana, para que el modelo no trate la notificación como una instrucción o aprobación del usuario.

Para detectar un turno de notificación de tarea, comprueba `origin.kind === "task-notification"` en el [`SDKUserMessage`](#sdkusermessage) o el [`SDKResultMessage`](#sdkresultmessage) en lugar de buscar coincidencias con el texto del aviso. Lee `subkind` del mismo campo si necesitas saber qué lo originó. Antes de v2.1.205, Claude Code no incluía el aviso en las notificaciones que llegaban mientras la sesión estaba inactiva.

<h3 id="sdktoolusesummarymessage">
  `SDKToolUseSummaryMessage`
</h3>

Resumen del uso de herramientas en una conversación.

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

<h3 id="sdkhookstartedmessage">
  `SDKHookStartedMessage`
</h3>

Se emite cuando un hook comienza a ejecutarse.

Claude Code entrega este mensaje, [`SDKHookProgressMessage`](#sdkhookprogressmessage) y [`SDKHookResponseMessage`](#sdkhookresponsemessage) al flujo de mensajes de inmediato, incluso mientras un hook `SessionStart` o `Setup` todavía se está ejecutando durante el inicio de la sesión. Claude Code v2.1.169 a v2.1.203 entregaba estos mensajes en un solo lote después de que un hook `SessionStart` o `Setup` se completaba; v2.1.204 restauró la entrega en vivo.

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

<h3 id="sdkhookprogressmessage">
  `SDKHookProgressMessage`
</h3>

Se emite mientras un hook se está ejecutando, con la salida de stdout/stderr.

```typescript theme={null}
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;
};
```

<h3 id="sdkhookresponsemessage">
  `SDKHookResponseMessage`
</h3>

Se emite cuando un hook termina de ejecutarse.

```typescript theme={null}
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;
};
```

<h3 id="sdktoolprogressmessage">
  `SDKToolProgressMessage`
</h3>

Se emite periódicamente mientras se ejecuta una herramienta para indicar el progreso.

```typescript theme={null}
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;
  heartbeat?: boolean;
  subagent_type?: string;
  subagent_retry?: {
    agent_id: string;
    attempt: number;
    max_retries: number;
    retry_delay_ms: number;
    error_status: number | null;
    error_category: string;
  };
  uuid: UUID;
  session_id: string;
};
```

Mientras una llamada a herramienta se ejecuta en la conversación principal, Claude Code emite un mensaje `tool_progress` cada 30 segundos con `heartbeat: true`. Cada latido lleva el nombre de la herramienta y los segundos transcurridos, para que puedas distinguir una llamada de larga duración de una sesión estancada. Claude Code no emite latidos para llamadas a herramientas dentro de un subagente. El campo `heartbeat` requiere Agent SDK v0.3.214 o posterior. Antes de v2.1.257, Claude Code tampoco emitía latidos para una llamada a la herramienta Agent en primer plano.

En los mensajes `tool_progress` de la herramienta Agent que no son latidos, `subagent_type` nombra el tipo de subagente en ejecución, como `general-purpose`. `subagent_retry` está presente mientras ese subagente espera el retroceso tras un error de API, como un rate limit o una sobrecarga, con un mensaje por intento de reintento. Ambos campos requieren Agent SDK v0.3.214 o posterior.

Para renderizar un indicador de reintento a partir de `subagent_retry`:

* Rastrea el indicador por `parent_tool_use_id`, que es único por subagente. `tool_use_id` lo comparten los subagentes paralelos de un mismo turno de asistente, así que rastrear por él permitiría que la actualización de un subagente borre el indicador de otro.
* Borra el indicador cuando llegue un `tool_progress` posterior para el mismo `parent_tool_use_id` sin `subagent_retry` ni `heartbeat: true`, o cuando llegue el mensaje de resultado de la herramienta. Los frames con `heartbeat: true` solo informan que el proceso sigue activo, así que conserva el indicador cuando llegue uno. `attempt` puede superar `max_retries` con reintento persistente, así que no determines el borrado a partir de los contadores.
* Trata `error_category` como un token para elegir tu propio texto de mensaje, no como texto para mostrar. Los valores son `rate_limit`, `overloaded`, `authentication_failed`, `server_error`, `cloud_credential_error` y `unknown`. Maneja un valor que no reconozcas igual que `unknown`, porque versiones posteriores pueden agregar valores.

<h3 id="sdkauthstatusmessage">
  `SDKAuthStatusMessage`
</h3>

Se emite durante los flujos de autenticación.

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

<h3 id="sdktaskstartedmessage">
  `SDKTaskStartedMessage`
</h3>

Se emite cuando comienza una tarea. El campo `task_type` es `"local_bash"` para comandos Bash y vigilancias de [Monitor](#monitor), `"local_agent"` para subagentes, o `"remote_agent"`.

```typescript theme={null}
type SDKTaskStartedMessage = {
  type: "system";
  subtype: "task_started";
  task_id: string;
  tool_use_id?: string;
  description: string;
  task_type?: string;
  is_backgrounded?: boolean;
  spawn_depth?: number;
  ambient?: boolean;
  uuid: UUID;
  session_id: string;
};
```

`ambient` es `true` para tareas que no forman parte del trabajo de la sesión, como las tareas que Claude Code ejecuta para su propio funcionamiento. Los vigilantes de actualización en vivo también son ambientales, incluidos los que pidió el usuario. Excluye las tareas ambientales de los indicadores de actividad. El campo requiere Agent SDK v0.3.247 o posterior.

`ambient` también aparece en [`SDKTaskNotificationMessage`](#sdktasknotificationmessage) y en las entradas de [`SDKBackgroundTasksChangedMessage`](#sdkbackgroundtaskschangedmessage).

`is_backgrounded` y `spawn_depth` describen cómo Claude Code inició la tarea. Ambos campos requieren Agent SDK v0.3.238 o posterior.

* `is_backgrounded`: Claude Code lo establece en tareas `"local_agent"` y `"local_bash"`. `true` significa que la tarea se ejecuta en segundo plano. `false` significa que la tarea se ejecuta en primer plano, y la llamada a herramienta que la inició permanece bloqueada hasta que la tarea termine o pase a segundo plano.
* `spawn_depth`: Claude Code lo establece solo en tareas `"local_agent"`. Un subagente creado por el hilo principal tiene profundidad `1`. Un subagente creado por un subagente de profundidad `1` tiene profundidad `2`, y así sucesivamente.

Un [subagente reanudado](/docs/es/agent-sdk/subagents#resume-subagents) siempre reporta `is_backgrounded: true`, porque Claude Code ejecuta todos los subagentes reanudados en segundo plano. Cuando una tarea en primer plano pasa más tarde a segundo plano, Claude Code reporta el nuevo valor de `is_backgrounded` en un mensaje [`task_updated`](#sdktaskupdatedmessage) en lugar de enviar un segundo `task_started`.

<h3 id="sdktaskprogressmessage">
  `SDKTaskProgressMessage`
</h3>

Se emite periódicamente mientras se ejecuta un subagente o una tarea en segundo plano.

Para una tarea de subagente, el campo `summary` lleva un resumen de progreso generado por el modelo y solo se completa cuando [`agentProgressSummaries`](#options) está habilitado. Para una [llamada a herramienta MCP en segundo plano](/docs/es/mcp#automatic-backgrounding-of-long-tool-calls), `summary` lleva el progreso más reciente reportado por el servidor MCP y no depende de esa opción.

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

<h3 id="sdktaskupdatedmessage">
  `SDKTaskUpdatedMessage`
</h3>

Se emite cuando cambia el estado de una tarea en segundo plano, por ejemplo cuando pasa de `running` a `completed`. Combina `patch` en tu mapa local de tareas indexado por `task_id`. El campo `end_time` es una marca de tiempo de época Unix en milisegundos, comparable con `Date.now()`.

```typescript theme={null}
type SDKTaskUpdatedMessage = {
  type: "system";
  subtype: "task_updated";
  task_id: string;
  patch: {
    status?: "pending" | "running" | "completed" | "failed" | "killed";
    description?: string;
    end_time?: number;
    total_paused_ms?: number;
    error?: string;
    is_backgrounded?: boolean;
  };
  uuid: UUID;
  session_id: string;
};
```

<h3 id="sdkbackgroundtaskschangedmessage">
  `SDKBackgroundTasksChangedMessage`
</h3>

Se emite siempre que cambia el conjunto de tareas en segundo plano activas: una tarea comienza, se completa o se termina, un agente en primer plano pasa a segundo plano, o cambia el campo `description` o `ambient` de una tarea.

El array `tasks` es el conjunto activo completo. Reemplaza cualquier conjunto en caché con cada payload en lugar de emparejar eventos `task_started` y `task_notification`, para que el siguiente cambio de membresía corrija cualquier evento que te hayas perdido.

El orden relativo a esos eventos por tarea no está especificado, así que no correlaciones los dos flujos.

No se emite nada al inicio. Restablece a un conjunto vacío cada vez que el proceso de CLI de la sesión se inicie o reinicie, y deja que el siguiente cambio de membresía lo vuelva a llenar.

Cuando envías una solicitud de control `initialize` repetida a una sesión en ejecución, como con [`reinitialize()`](#query-object) después de una interrupción del transporte, Claude Code envía tras la respuesta una instantánea del conjunto activo actual, incluso cuando está vacío. Así, un host que se reconecta sabe qué se está ejecutando sin esperar al siguiente cambio de membresía. Antes de Agent SDK v0.3.239, Claude Code no enviaba ninguna instantánea después de un `initialize` repetido.

Requiere Claude Code v2.1.203 o posterior.

```typescript theme={null}
type SDKBackgroundTasksChangedMessage = {
  type: "system";
  subtype: "background_tasks_changed";
  tasks: {
    task_id: string;
    task_type: string;
    description: string;
    ambient?: boolean;
  }[];
  uuid: UUID;
  session_id: string;
};
```

<h3 id="sdkthinkingtokensmessage">
  `SDKThinkingTokensMessage`
</h3>

Se emite mientras Claude produce un bloque de pensamiento, incluido uno redactado. `estimated_tokens` es una estimación acumulada de los tokens de pensamiento generados hasta el momento en el bloque actual, y `estimated_tokens_delta` es el incremento que lleva este frame. Usa estas estimaciones para mostrar el progreso.

Cuando el modelo o el proveedor reporta un desglose, el recuento final del bucle de agente de nivel superior es el [`usage.output_tokens_details.thinking_tokens`](#usage) del mensaje de resultado, que [no incluye tokens de subagentes](/docs/es/agent-sdk/cost-tracking#get-the-total-cost-of-a-query).

Requiere Claude Code v2.1.153 o posterior.

```typescript theme={null}
type SDKThinkingTokensMessage = {
  type: "system";
  subtype: "thinking_tokens";
  estimated_tokens: number;
  estimated_tokens_delta: number;
  user_message_uuid?: string;
  uuid: UUID;
  session_id: string;
};
```

<h3 id="sdksessionstatechangedmessage">
  `SDKSessionStateChangedMessage`
</h3>

Se emite cuando Claude Code reporta el estado de la sesión. Para recibir estos mensajes, establece [`CLAUDE_CODE_EMIT_SESSION_STATE_EVENTS=1`](/docs/es/env-vars#variables). Claude Code puede reportar el mismo estado más de una vez, así que interpreta un mensaje como el estado actual de la sesión y no como una transición.

El campo `state` lleva uno de estos valores:

* `running`: la sesión está trabajando.
* `idle`: Claude Code está esperando tu siguiente prompt.
* `requires_action`: la sesión está bloqueada a la espera de una respuesta a una solicitud que envió a tu host, como una solicitud de permiso.

El mensaje `idle` de un turno y su mensaje `result` pueden llegar en cualquier orden. Para cambiar si `idle` espera el trabajo en segundo plano, como un subagente en segundo plano o una ejecución de un [flujo de trabajo](/docs/es/workflows), consulta [`CLAUDE_CODE_BG_TASKS_REPORT_RUNNING`](/docs/es/env-vars#variables).

```typescript theme={null}
type SDKSessionStateChangedMessage = {
  type: "system";
  subtype: "session_state_changed";
  state: "idle" | "running" | "requires_action";
  uuid: UUID;
  session_id: string;
};
```

<h3 id="sdkfilespersistedevent">
  `SDKFilesPersistedEvent`
</h3>

Se emite cuando los checkpoints de archivos se guardan en el disco.

```typescript theme={null}
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;
};
```

<h3 id="sdkratelimitevent">
  `SDKRateLimitEvent`
</h3>

Se emite cuando la sesión encuentra un rate limit.

```typescript theme={null}
type SDKRateLimitEvent = {
  type: "rate_limit_event";
  rate_limit_info: {
    status: "allowed" | "allowed_warning" | "rejected";
    resetsAt?: number;
    utilization?: number;
    errorCode?: "credits_required";
    canUserPurchaseCredits?: boolean;
    hasChargeableSavedPaymentMethod?: boolean;
  };
  uuid: UUID;
  session_id: string;
};
```

Cuando `errorCode` es `"credits_required"`, el rechazo proviene de una suscripción de claude.ai cuyo uso incluido se ha agotado, y la sesión no puede continuar hasta que el usuario compre créditos de uso. `canUserPurchaseCredits` indica si el usuario autenticado puede comprar créditos para la cuenta, y `hasChargeableSavedPaymentMethod` indica si hay un método de pago guardado registrado. Los tres campos están ausentes en los eventos de rate limit que no son rechazos por créditos requeridos. Requiere Claude Code v2.1.181 o posterior.

<h3 id="sdklocalcommandoutputmessage">
  `SDKLocalCommandOutputMessage`
</h3>

Claude Code no emite este tipo de mensaje. Cuando envías un comando como `/context` o `/usage` como prompt, su salida llega como un [`SDKAssistantMessage`](#sdkassistantmessage).

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

<h3 id="sdkcommandschangedmessage">
  `SDKCommandsChangedMessage`
</h3>

Se emite cuando el conjunto de comandos disponibles cambia a mitad de la sesión, por ejemplo cuando Claude Code descubre skills a medida que el agente entra en un subdirectorio. El array `commands` es la lista completa actualizada, así que reemplaza cualquier lista de comandos en caché con este payload. Llamar a [`supportedCommands()`](#query-object) después de este mensaje devuelve la misma lista actualizada, porque el método sigue el envío más reciente; esto requiere Agent SDK v0.3.216 o posterior. En versiones anteriores del SDK, `supportedCommands()` devuelve la instantánea capturada en la inicialización y nunca refleja los cambios a mitad de la sesión.

Claude Code también emite este mensaje cuando los [prompts](/docs/es/mcp#use-mcp-prompts-as-commands) de un servidor MCP entran o salen de la lista, por ejemplo cuando un servidor termina de conectarse después de que comienza la sesión. Esto requiere Claude Code v2.1.281 o posterior.

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

<h3 id="sdkpromptsuggestionmessage">
  `SDKPromptSuggestionMessage`
</h3>

Se emite después de un turno cuando [`promptSuggestions`](#options) está habilitado y Claude Code generó una sugerencia para ese turno. Contiene el siguiente prompt del usuario previsto. Para los turnos que no reciben ninguna, consulta [Cuándo Claude Code omite sugerencias](/docs/es/interactive-mode#when-claude-code-skips-suggestions).

```typescript theme={null}
type SDKPromptSuggestionMessage = {
  type: "prompt_suggestion";
  suggestion: string;
  uuid: UUID;
  session_id: string;
};
```

<h3 id="sdkconversationresetmessage">
  `SDKConversationResetMessage`
</h3>

Se emite cuando la conversación de la sesión se reemplaza sin terminar la sesión. En una llamada a `query()`, solo `/clear` y sus alias producen este mensaje. Monta una transcripción vacía bajo `new_conversation_id` y descarta cualquier título de sesión en caché.

```typescript theme={null}
type SDKConversationResetMessage = {
  type: "conversation_reset";
  new_conversation_id: UUID;
  uuid: UUID;
  session_id: string;
  trigger?: "clear" | "plan_mode_exit" | "fresh_session" | "onboarding";
  user_message_uuid?: string;
  timestamp?: string;
};
```

Los campos opcionales describen el reinicio:

* `trigger`: qué descartó la conversación. Reinicia tu transcripción en cada mensaje `conversation_reset`, incluido uno en el que este campo esté ausente o lleve un valor que no reconozcas.
* `user_message_uuid`: el `uuid` del mensaje de usuario que llevaba el `/clear`. Úsalo para asociar el reinicio con ese mensaje.
* `timestamp`: cuándo ocurrió el reinicio, como una cadena ISO 8601 en UTC. Úsalo para mostrarlo, no para ordenar mensajes.

Los campos `trigger`, `user_message_uuid` y `timestamp` requieren Claude Code v2.1.281 o posterior.

Las definiciones de tipos publicadas del SDK declaran `SDKConversationResetMessage` en Claude Code v2.1.203 y posterior. Antes de v2.1.203, `SDKMessage` hacía referencia al tipo sin declararlo, por lo que el estrechamiento con `type === "conversation_reset"` no pasaba la verificación de tipos cuando `skipLibCheck` estaba deshabilitado.

<h3 id="aborterror">
  `AbortError`
</h3>

Clase de error personalizada para operaciones de aborto.

```typescript theme={null}
class AbortError extends Error {}
```

`AbortError` es la única clase de error en la API tipada del SDK. Otros fallos, como que el proceso de Claude Code termine o no logre iniciarse, rechazan la iteración de mensajes con errores que no tienen ninguna clase del SDK con la que comparar. [Solución de problemas](/docs/es/agent-sdk/troubleshooting) organiza esos errores por mensaje, con la causa y la solución de cada uno.

<h2 id="sandbox-configuration">
  Configuración de Sandbox
</h2>

<h3 id="sandboxsettings">
  `SandboxSettings`
</h3>

Configuración para el comportamiento de sandbox. Use esto para habilitar el sandboxing de comandos y configurar restricciones de red mediante programación.

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

| Propiedad | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `enabled` | `boolean` | `false` | Habilite el modo sandbox para la ejecución de comandos |
| `failIfUnavailable` | `boolean` | `true` | Deténgase al inicio si `enabled` es `true` pero el sandbox no puede iniciarse. Establezca `false` para recurrir a la ejecución sin sandbox con una advertencia en stderr |
| `autoAllowBashIfSandboxed` | `boolean` | `true` | Auto-apruebe comandos Bash cuando el sandbox está habilitado |
| `excludedCommands` | `string[]` | `[]` | Comandos que omiten restricciones de sandbox, como `['docker *']`. Estos se ejecutan sin sandbox automáticamente sin participación del modelo; [`sandbox.excludedCommands`](/docs/es/settings-reference#sandbox-excludedcommands) cubre cuándo se aplica una entrada |
| `allowUnsandboxedCommands` | `boolean` | `true` | Permita que el modelo solicite ejecutar comandos fuera del sandbox. Cuando es `true`, el modelo puede establecer `dangerouslyDisableSandbox` en la entrada de herramienta, que se vuelve al [sistema de permisos](#permissions-fallback-for-unsandboxed-commands) |
| `network` | [`SandboxNetworkConfig`](#sandboxnetworkconfig) | `undefined` | Configuración de sandbox específica de red |
| `filesystem` | [`SandboxFilesystemConfig`](#sandboxfilesystemconfig) | `undefined` | Configuración de sandbox específica del sistema de archivos para restricciones de lectura/escritura |
| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Mapa de subcadenas de comando, o `*` para cada comando, a subcadenas del texto de violación a ignorar, como `{ "*": ['/etc/hosts'] }`; consulte [`sandbox.ignoreViolations`](/docs/es/settings-reference#sandbox-ignoreviolations) |
| `enableWeakerNestedSandbox` | `boolean` | `false` | Habilite un sandbox anidado más débil para compatibilidad |
| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configuración de binario ripgrep personalizado para entornos sandbox |

<Note>
  El sandbox depende de la compatibilidad de la plataforma y, en Linux, de herramientas como `bubblewrap` y `socat`. Cuando `enabled` es `true` y el sandbox no puede iniciarse, `query()` reporta un mensaje `result` con `subtype: "error_during_execution"` y la razón en `errors`. Para una única llamada a `query()`, el SDK lanza después de ceder ese resultado de error, así que envuelva el bucle en un bloque try para continuar más allá. Consulte [Manejar el resultado](/docs/es/agent-sdk/agent-loop#handle-the-result) para el contrato de error.

  Para ejecutar sin sandbox en su lugar, establezca `failIfUnavailable: false`.
</Note>

<h4 id="example-usage">
  Ejemplo de uso
</h4>

```typescript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";

try {
  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);
  }
} catch (error) {
  // A single-shot query() throws after yielding an error result,
  // such as when the sandbox can't start (failIfUnavailable defaults to true).
  console.log(`Session ended with an error: ${error}`);
}
```

<Warning>
  **Seguridad de socket Unix:** La opción `allowUnixSockets` puede otorgar acceso a servicios del sistema que alcanzan fuera del sandbox. Por ejemplo, permitir `/var/run/docker.sock` efectivamente otorga acceso completo al sistema host a través de la API de Docker, omitiendo el aislamiento de sandbox. Solo permita sockets Unix que sean estrictamente necesarios y comprenda las implicaciones de seguridad de cada uno.
</Warning>

<h3 id="sandboxnetworkconfig">
  `SandboxNetworkConfig`
</h3>

Configuración específica de red para el modo sandbox. Estas configuraciones se aplican a comandos Bash en sandbox cuando `enabled` es `true` en la [`SandboxSettings`](#sandboxsettings) principal. No restringen la herramienta WebFetch, que utiliza [reglas de permisos](/docs/es/permissions#webfetch) en su lugar.

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

| Propiedad | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `allowedDomains` | `string[]` | `[]` | Nombres de dominio a los que los procesos en sandbox pueden acceder |
| `deniedDomains` | `string[]` | `[]` | Nombres de dominio a los que los procesos en sandbox no pueden acceder. Tiene prioridad sobre `allowedDomains` |
| `strictAllowlist` | `boolean` | `false` | Niegue a los comandos en sandbox el acceso a hosts fuera de la [lista de permitidos de red](/docs/es/sandboxing#network-isolation) en lugar de solicitar. Se aplica solo a comandos en sandbox; las herramientas en proceso como WebFetch no están controladas por esto. Solo se respeta desde la configuración de usuario, administrada o CLI `--settings`; la configuración del proyecto se ignora. Requiere Claude Code v2.1.219 o posterior |
| `allowManagedDomainsOnly` | `boolean` | `false` | Solo configuración administrada. Cuando se establece en [configuración administrada](/docs/es/managed-settings), solo se respetan las entradas `allowedDomains` y las reglas de permitir `WebFetch(domain:...)` de la configuración administrada, y se ignoran las entradas de permitir de la configuración de usuario, proyecto o local. Desde el SDK, páselo a través de la opción [`managedSettings`](#options) |
| `allowLocalBinding` | `boolean` | `false` | Permita que los procesos se vinculen a puertos locales (por ejemplo, para servidores de desarrollo) |
| `allowUnixSockets` | `string[]` | `[]` | Rutas de socket Unix a las que los procesos pueden acceder (por ejemplo, socket de Docker) |
| `allowAllUnixSockets` | `boolean` | `false` | Permita el acceso a todos los sockets Unix |
| `httpProxyPort` | `number` | `undefined` | Puerto proxy HTTP para solicitudes de red |
| `socksProxyPort` | `number` | `undefined` | Puerto proxy SOCKS para solicitudes de red |

<Note>
  El proxy de sandbox integrado aplica `allowedDomains` basándose en el nombre de host solicitado y no termina ni inspecciona el tráfico TLS, por lo que técnicas como [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) potencialmente pueden omitirlo. Consulte [Limitaciones de seguridad de sandboxing](/docs/es/sandboxing#security-limitations) para obtener detalles y [Implementación segura](/docs/es/agent-sdk/secure-deployment#traffic-forwarding) para configurar un proxy que termine TLS.
</Note>

<h3 id="sandboxfilesystemconfig">
  `SandboxFilesystemConfig`
</h3>

Configuración específica del sistema de archivos para el modo sandbox.

```typescript theme={null}
type SandboxFilesystemConfig = {
  allowWrite?: string[];
  denyWrite?: string[];
  denyRead?: string[];
};
```

| Propiedad | Tipo | Predeterminado | Descripción |
| :- | :- | :- | :- |
| `allowWrite` | `string[]` | `[]` | Patrones de ruta de archivo para permitir acceso de escritura a |
| `denyWrite` | `string[]` | `[]` | Patrones de ruta de archivo para negar acceso de escritura a |
| `denyRead` | `string[]` | `[]` | Patrones de ruta de archivo para negar acceso de lectura a |

<h3 id="permissions-fallback-for-unsandboxed-commands">
  Fallback de Permisos para Comandos Sin Sandbox
</h3>

Cuando `allowUnsandboxedCommands` está habilitado, el modelo puede solicitar ejecutar comandos fuera del sandbox estableciendo `dangerouslyDisableSandbox: true` en la entrada de herramienta. Estas solicitudes se vuelven al sistema de permisos existente, lo que significa que se invoca su controlador `canUseTool`, permitiéndole implementar lógica de autorización personalizada.

Sus entradas `excludedCommands` en su lugar omiten el sandbox sin participación del modelo; [`sandbox.excludedCommands`](/docs/es/settings-reference#sandbox-excludedcommands) cubre cuándo se aplica una entrada.

En el ejemplo siguiente, `isCommandAuthorized` representa una verificación de autorización que usted define.

```typescript theme={null}
import { query } from "@anthropic-ai/claude-agent-sdk";

for await (const message of query({
  prompt: "Deploy my application",
  options: {
    sandbox: {
      enabled: true,
      allowUnsandboxedCommands: true // El modelo puede solicitar ejecución sin sandbox
    },
    permissionMode: "default",
    canUseTool: async (tool, input) => {
      // Verifique si el modelo está solicitando omitir el sandbox
      if (tool === "Bash" && input.dangerouslyDisableSandbox) {
        // El modelo está solicitando ejecutar este comando fuera del 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);
}
```

<Warning>
  Los comandos que se ejecutan con `dangerouslyDisableSandbox: true` tienen acceso completo al sistema. Asegúrese de que su controlador `canUseTool` valide estas solicitudes cuidadosamente.

  Si `permissionMode` se establece en `bypassPermissions` y `allowUnsandboxedCommands` está habilitado, el modelo puede ejecutar autónomamente comandos fuera del sandbox sin solicitudes de aprobación, aparte de las [acciones que ningún modo auto-aprueba](/docs/es/permission-modes#actions-no-mode-auto-approves). Esta combinación efectivamente permite que el modelo escape del aislamiento de sandbox silenciosamente.
</Warning>

<h2 id="see-also">
  Ver también
</h2>

* [Descripción general del SDK](/docs/es/agent-sdk/overview) - Conceptos generales del SDK
* [Referencia del SDK de Python](/docs/es/agent-sdk/python) - Documentación del SDK de Python
* [Referencia de CLI](/docs/es/cli-reference) - Interfaz de línea de comandos
* [Flujos de trabajo comunes](/docs/es/common-workflows) - Guías paso a paso