Documentation — Spybara

agent-sdk/agent-loop.md +395 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Cómo funciona el bucle del agente

7> Comprenda el ciclo de vida de los mensajes, la ejecución de herramientas, la ventana de contexto y la arquitectura que potencia sus agentes SDK.

9El Agent SDK le permite incrustar el bucle de agente autónomo de Claude Code en sus propias aplicaciones. El SDK es un paquete independiente que le proporciona control programático sobre herramientas, permisos, límites de costos y salida. No necesita tener instalado el CLI de Claude Code para usarlo.

11Cuando inicia un agente, el SDK ejecuta el mismo [bucle de ejecución que potencia Claude Code](/es/how-claude-code-works#the-agentic-loop): Claude evalúa su prompt, llama a herramientas para tomar acciones, recibe los resultados y repite hasta que la tarea se complete. Esta página explica qué sucede dentro de ese bucle para que pueda construir, depurar y optimizar sus agentes de manera efectiva.

13## El bucle de un vistazo

15Cada sesión de agente sigue el mismo ciclo:

17<img src="https://mintcdn.com/claude-code/gvy2DIUELtNA8qD3/images/agent-loop-diagram.svg?fit=max&auto=format&n=gvy2DIUELtNA8qD3&q=85&s=192e1bd6c8a2950a16e5ee0b94e27e26" alt="Bucle del agente: el prompt entra, Claude evalúa, se ramifica a llamadas de herramientas o respuesta final" width="680" height="150" data-path="images/agent-loop-diagram.svg" />

191. **Recibir prompt.** Claude recibe su prompt, junto con el prompt del sistema, las definiciones de herramientas e historial de conversación. El SDK produce un [`SystemMessage`](#message-types) con subtipo `"init"` que contiene metadatos de sesión.

202. **Evaluar y responder.** Claude evalúa el estado actual y determina cómo proceder. Puede responder con texto, solicitar una o más llamadas de herramientas, o ambas. El SDK produce un [`AssistantMessage`](#message-types) que contiene el texto y cualquier solicitud de llamada de herramienta.

213. **Ejecutar herramientas.** El SDK ejecuta cada herramienta solicitada y recopila los resultados. Cada conjunto de resultados de herramientas se devuelve a Claude para la siguiente decisión. Puede usar [hooks](/es/agent-sdk/hooks) para interceptar, modificar o bloquear llamadas de herramientas antes de que se ejecuten.

224. **Repetir.** Los pasos 2 y 3 se repiten como un ciclo. Cada ciclo completo es un turno. Claude continúa llamando a herramientas y procesando resultados hasta que produce una respuesta sin llamadas de herramientas.

235. **Devolver resultado.** El SDK produce un [`AssistantMessage`](#message-types) final con la respuesta de texto (sin llamadas de herramientas), seguido de un [`ResultMessage`](#message-types) con el texto final, uso de tokens, costo e ID de sesión.

25Una pregunta rápida ("¿qué archivos hay aquí?") podría tomar uno o dos turnos llamando a `Glob` y respondiendo con los resultados. Una tarea compleja ("refactorizar el módulo de autenticación y actualizar las pruebas") puede encadenar docenas de llamadas de herramientas en muchos turnos, leyendo archivos, editando código y ejecutando pruebas, con Claude ajustando su enfoque basado en cada resultado.

27## Turnos y mensajes

29Un turno es un viaje de ida y vuelta dentro del bucle: Claude produce una salida que incluye llamadas de herramientas, el SDK ejecuta esas herramientas y los resultados se devuelven a Claude automáticamente. Esto sucede sin ceder el control a su código. Los turnos continúan hasta que Claude produce una salida sin llamadas de herramientas, momento en el cual el bucle termina y se entrega el resultado final.

31Considere cómo podría verse una sesión completa para el prompt "Arregla las pruebas fallidas en auth.ts".

33Primero, el SDK envía su prompt a Claude y produce un [`SystemMessage`](#message-types) con los metadatos de sesión. Luego comienza el bucle:

351. **Turno 1:** Claude llama a `Bash` para ejecutar `npm test`. El SDK produce un [`AssistantMessage`](#message-types) con la llamada de herramienta, ejecuta el comando, luego produce un [`UserMessage`](#message-types) con la salida (tres fallos).

362. **Turno 2:** Claude llama a `Read` en `auth.ts` y `auth.test.ts`. El SDK devuelve el contenido del archivo y produce un `AssistantMessage`.

373. **Turno 3:** Claude llama a `Edit` para arreglar `auth.ts`, luego llama a `Bash` para volver a ejecutar `npm test`. Las tres pruebas pasan. El SDK produce un `AssistantMessage`.

384. **Turno final:** Claude produce una respuesta solo de texto sin llamadas de herramientas: "Arreglé el error de autenticación, las tres pruebas pasan ahora." El SDK produce un `AssistantMessage` final con este texto, luego un [`ResultMessage`](#message-types) con el mismo texto más costo y uso.

40Eso fueron cuatro turnos: tres con llamadas de herramientas, uno con respuesta final solo de texto.

42Puede limitar el bucle con `max_turns` / `maxTurns`, que cuenta solo los turnos de uso de herramientas. Por ejemplo, `max_turns=2` en el bucle anterior se habría detenido antes del paso de edición. También puede usar `max_budget_usd` / `maxBudgetUsd` para limitar los turnos basándose en un umbral de gasto.

44Sin límites, el bucle se ejecuta hasta que Claude termine por su cuenta, lo cual está bien para tareas bien delimitadas pero puede ejecutarse durante mucho tiempo en prompts abiertos ("mejora esta base de código"). Establecer un presupuesto es un buen valor predeterminado para agentes de producción. Vea [Turnos y presupuesto](#turns-and-budget) a continuación para la referencia de opciones.

46## Tipos de mensajes

48A medida que se ejecuta el bucle, el SDK produce un flujo de mensajes. Cada mensaje lleva un tipo que le indica en qué etapa del bucle se originó. Los cinco tipos principales son:

50* **`SystemMessage`:** eventos del ciclo de vida de la sesión. El campo `subtype` los distingue: `"init"` es el primer mensaje (metadatos de sesión), y `"compact_boundary"` se dispara después de [compactación](#automatic-compaction). En TypeScript, el límite de compactación es su propio tipo [`SDKCompactBoundaryMessage`](/es/agent-sdk/typescript#sdkcompactboundarymessage) en lugar de un subtipo de `SDKSystemMessage`.

51* **`AssistantMessage`:** emitido después de cada respuesta de Claude, incluida la final solo de texto. Contiene bloques de contenido de texto y bloques de llamadas de herramientas de ese turno.

52* **`UserMessage`:** emitido después de cada ejecución de herramienta con el contenido del resultado de la herramienta enviado de vuelta a Claude. También se emite para cualquier entrada de usuario que transmita a mitad del bucle.

53* **`StreamEvent`:** solo se emite cuando los mensajes parciales están habilitados. Contiene eventos de transmisión de API sin procesar (deltas de texto, fragmentos de entrada de herramientas). Vea [Respuestas de transmisión](/es/agent-sdk/streaming-output).

54* **`ResultMessage`:** marca el final del bucle del agente. Contiene el resultado de texto final, uso de tokens, costo e ID de sesión. Verifique el campo `subtype` para determinar si la tarea tuvo éxito o alcanzó un límite. Un pequeño número de eventos del sistema finales, como `prompt_suggestion`, pueden llegar después, así que itere el flujo hasta completarse en lugar de romper en el resultado. Vea [Manejar el resultado](#handle-the-result).

56Estos cinco tipos cubren el ciclo de vida completo del bucle del agente en ambos SDK. El SDK de TypeScript también produce eventos de observabilidad adicionales (eventos de hooks, progreso de herramientas, límites de velocidad, notificaciones de tareas) que proporcionan detalles adicionales pero no son necesarios para impulsar el bucle. Vea la [referencia de tipos de mensajes de Python](/es/agent-sdk/python#message-types) y la [referencia de tipos de mensajes de TypeScript](/es/agent-sdk/typescript#message-types) para las listas completas.

58### Manejar mensajes

60Qué mensajes maneja depende de lo que esté construyendo:

62* **Solo resultados finales:** maneje `ResultMessage` para obtener la salida, el costo y si la tarea tuvo éxito o alcanzó un límite.

63* **Actualizaciones de progreso:** maneje `AssistantMessage` para ver qué está haciendo Claude en cada turno, incluidas las herramientas que llamó.

64* **Transmisión en vivo:** habilite mensajes parciales (`include_partial_messages` en Python, `includePartialMessages` en TypeScript) para obtener mensajes `StreamEvent` en tiempo real. Vea [Respuestas de transmisión en tiempo real](/es/agent-sdk/streaming-output).

66Cómo verifica los tipos de mensajes depende del SDK:

68* **Python:** verifique los tipos de mensajes con `isinstance()` contra clases importadas de `claude_agent_sdk` (por ejemplo, `isinstance(message, ResultMessage)`).

69* **TypeScript:** verifique el campo de cadena `type` (por ejemplo, `message.type === "result"`). `AssistantMessage` y `UserMessage` envuelven el mensaje de API sin procesar en un campo `.message`, por lo que los bloques de contenido están en `message.message.content`, no en `message.content`.

71<Accordion title="Ejemplo: Verificar tipos de mensajes y manejar resultados">

72 <CodeGroup>

73 ```python Python theme={null}

74 from claude_agent_sdk import query, AssistantMessage, ResultMessage

76 async for message in query(prompt="Summarize this project"):

77 if isinstance(message, AssistantMessage):

78 print(f"Turn completed: {len(message.content)} content blocks")

79 if isinstance(message, ResultMessage):

80 if message.subtype == "success":

81 print(message.result)

82 else:

83 print(f"Stopped: {message.subtype}")

84 ```

86 ```typescript TypeScript theme={null}

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

89 for await (const message of query({ prompt: "Summarize this project" })) {

90 if (message.type === "assistant") {

91 console.log(`Turn completed: ${message.message.content.length} content blocks`);

92 }

93 if (message.type === "result") {

94 if (message.subtype === "success") {

95 console.log(message.result);

96 } else {

97 console.log(`Stopped: ${message.subtype}`);

98 }

99 }

100 }

101 ```

102 </CodeGroup>

103</Accordion>

104

105## Ejecución de herramientas

106

107Las herramientas dan a su agente la capacidad de tomar acciones. Sin herramientas, Claude solo puede responder con texto. Con herramientas, Claude puede leer archivos, ejecutar comandos, buscar código e interactuar con servicios externos.

108

109### Herramientas integradas

110

111El SDK incluye las mismas herramientas que potencian Claude Code:

112

113| Categoría | Herramientas | Qué hacen |

114| :------------------------- | :----------------------------------------------- | :------------------------------------------------------------------------------------- |

115| **Operaciones de archivo** | `Read`, `Edit`, `Write` | Leer, modificar y crear archivos |

116| **Búsqueda** | `Glob`, `Grep` | Encontrar archivos por patrón, buscar contenido con regex |

117| **Ejecución** | `Bash` | Ejecutar comandos de shell, scripts, operaciones de git |

118| **Web** | `WebSearch`, `WebFetch` | Buscar en la web, obtener y analizar páginas |

119| **Descubrimiento** | `ToolSearch` | Encontrar y cargar herramientas dinámicamente bajo demanda en lugar de precargar todas |

120| **Orquestación** | `Agent`, `Skill`, `AskUserQuestion`, `TodoWrite` | Generar subagentes, invocar skills, preguntar al usuario, rastrear tareas |

121

122Más allá de las herramientas integradas, puede:

123

124* **Conectar servicios externos** con [servidores MCP](/es/agent-sdk/mcp) (bases de datos, navegadores, APIs)

125* **Definir herramientas personalizadas** con [manejadores de herramientas personalizadas](/es/agent-sdk/custom-tools)

126* **Cargar skills del proyecto** a través de [fuentes de configuración](/es/agent-sdk/claude-code-features) para flujos de trabajo reutilizables

127

128### Permisos de herramientas

129

130Claude determina qué herramientas llamar basándose en la tarea, pero usted controla si esas llamadas pueden ejecutarse. Puede aprobar automáticamente herramientas específicas, bloquear otras completamente o requerir aprobación para todo. Tres opciones funcionan juntas para determinar qué se ejecuta:

131

132* **`allowed_tools` / `allowedTools`** aprueba automáticamente las herramientas listadas. Un agente de solo lectura con `["Read", "Glob", "Grep"]` en su lista de herramientas permitidas ejecuta esas herramientas sin solicitar. Las herramientas no listadas aún están disponibles pero requieren permiso.

133* **`disallowed_tools` / `disallowedTools`** bloquea las herramientas listadas, independientemente de otras configuraciones. Vea [Permisos](/es/agent-sdk/permissions) para el orden en que se verifican las reglas antes de que se ejecute una herramienta.

134* **`permission_mode` / `permissionMode`** controla qué sucede con las herramientas que no están cubiertas por reglas de permitir o denegar. Vea [Modo de permiso](#permission-mode) para los modos disponibles.

135

136También puede limitar herramientas individuales con reglas como `"Bash(npm *)"` para permitir solo comandos específicos. Vea [Permisos](/es/agent-sdk/permissions) para la sintaxis completa de reglas.

137

138Cuando se deniega una herramienta, Claude recibe un mensaje de rechazo como resultado de la herramienta e intenta típicamente un enfoque diferente o reporta que no pudo proceder.

139

140### Ejecución paralela de herramientas

141

142Cuando Claude solicita múltiples llamadas de herramientas en un solo turno, ambos SDK pueden ejecutarlas concurrentemente o secuencialmente dependiendo de la herramienta. Las herramientas de solo lectura (como `Read`, `Glob`, `Grep` y herramientas MCP marcadas como de solo lectura) pueden ejecutarse concurrentemente. Las herramientas que modifican estado (como `Edit`, `Write` y `Bash`) se ejecutan secuencialmente para evitar conflictos.

143

144Las herramientas personalizadas tienen ejecución secuencial de forma predeterminada. Para habilitar la ejecución paralela para una herramienta personalizada, establezca `readOnlyHint` en sus anotaciones. Ambos SDK de [TypeScript](/es/agent-sdk/typescript#tool) y [Python](/es/agent-sdk/python#tool) usan este nombre de campo del SDK de MCP.

145

146## Controlar cómo se ejecuta el bucle

147

148Puede limitar cuántos turnos toma el bucle, cuánto cuesta, cuán profundamente razona Claude y si las herramientas requieren aprobación antes de ejecutarse. Todos estos son campos en [`ClaudeAgentOptions`](/es/agent-sdk/python#claudeagentoptions) (Python) / [`Options`](/es/agent-sdk/typescript#options) (TypeScript).

149

150### Turnos y presupuesto

151

152| Opción | Qué controla | Predeterminado |

153| :----------------------------------------------------- | :------------------------------------------------------ | :------------- |

154| Máximo de turnos (`max_turns` / `maxTurns`) | Máximo de viajes de ida y vuelta de uso de herramientas | Sin límite |

155| Presupuesto máximo (`max_budget_usd` / `maxBudgetUsd`) | Costo máximo antes de detener | Sin límite |

156

157Cuando se alcanza cualquiera de los límites, el SDK devuelve un `ResultMessage` con un subtipo de error correspondiente (`error_max_turns` o `error_max_budget_usd`). Vea [Manejar el resultado](#handle-the-result) para cómo verificar estos subtipos y [`ClaudeAgentOptions`](/es/agent-sdk/python#claudeagentoptions) / [`Options`](/es/agent-sdk/typescript#options) para la sintaxis.

158

159### Nivel de esfuerzo

160

161La opción `effort` controla cuánto razonamiento aplica Claude. Los niveles de esfuerzo más bajos usan menos tokens por turno y reducen el costo. No todos los modelos soportan el parámetro de esfuerzo. Vea [Esfuerzo](https://platform.claude.com/docs/en/build-with-claude/effort) para qué modelos lo soportan.

162

163| Nivel | Comportamiento | Bueno para |

164| :--------- | :-------------------------------------- | :----------------------------------------------------------- |

165| `"low"` | Razonamiento mínimo, respuestas rápidas | Búsquedas de archivos, listado de directorios |

166| `"medium"` | Razonamiento equilibrado | Ediciones rutinarias, tareas estándar |

167| `"high"` | Análisis exhaustivo | Refactorizaciones, depuración |

168| `"xhigh"` | Profundidad de razonamiento extendida | Tareas de codificación y agentes; recomendado en Opus 4.7 |

169| `"max"` | Profundidad de razonamiento máxima | Problemas de múltiples pasos que requieren análisis profundo |

170

171Si no establece `effort`, el SDK de Python deja el parámetro sin establecer y se remite al comportamiento predeterminado del modelo. El SDK de TypeScript tiene como predeterminado `"high"`.

172

173<Note>

174 `effort` intercambia latencia y costo de token por profundidad de razonamiento dentro de cada respuesta. [Extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) es una característica separada que produce bloques de cadena de pensamiento visibles en la salida. Son independientes: puede establecer `effort: "low"` con extended thinking habilitado, o `effort: "max"` sin él.

175</Note>

176

177Use esfuerzo más bajo para agentes que realizan tareas simples y bien delimitadas (como listar archivos o ejecutar un único grep) para reducir costo y latencia. Establezca `effort` en las opciones de nivel superior `query()` para toda la sesión, o por subagente con el campo `effort` en [`AgentDefinition`](/es/agent-sdk/subagents#agentdefinition-configuration) para anular el nivel de sesión.

178

179### Modo de permiso

180

181La opción de modo de permiso (`permission_mode` en Python, `permissionMode` en TypeScript) controla si el agente solicita aprobación antes de usar herramientas:

182

183| Modo | Comportamiento |

184| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

185| `"default"` | Las herramientas no cubiertas por reglas de permitir activan su devolución de llamada de aprobación; sin devolución de llamada significa denegar |

186| `"acceptEdits"` | Aprueba automáticamente ediciones de archivo y comandos comunes del sistema de archivos (`mkdir`, `touch`, `mv`, `cp`, etc.); otros comandos de Bash siguen reglas predeterminadas |

187| `"plan"` | Las herramientas de solo lectura se ejecutan; Claude explora y produce un plan sin editar sus archivos fuente |

188| `"dontAsk"` | Nunca solicita. Las herramientas preaprobadas por [reglas de permiso](/es/settings#permission-settings) se ejecutan, todo lo demás se deniega |

189| `"auto"` (solo TypeScript) | Usa un clasificador de modelo para aprobar o denegar cada llamada de herramienta. Vea [Modo automático](/es/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidad y comportamiento |

190| `"bypassPermissions"` | Ejecuta todas las herramientas permitidas sin preguntar. No se puede usar cuando se ejecuta como root en Unix. Use solo en entornos aislados donde las acciones del agente no pueden afectar sistemas que le importan |

191

192Para aplicaciones interactivas, use `"default"` con una devolución de llamada de aprobación de herramienta para mostrar solicitudes de aprobación. Para agentes autónomos en una máquina de desarrollo, `"acceptEdits"` aprueba automáticamente ediciones de archivo y comandos comunes del sistema de archivos (`mkdir`, `touch`, `mv`, `cp`, etc.) mientras aún controla otros comandos de `Bash` detrás de reglas de permitir. Reserve `"bypassPermissions"` para CI, contenedores u otros entornos aislados. Vea [Permisos](/es/agent-sdk/permissions) para detalles completos.

193

194### Modelo

195

196Si no establece `model`, el SDK usa el predeterminado de Claude Code, que depende de su método de autenticación y suscripción. Establézcalo explícitamente (por ejemplo, `model="claude-sonnet-4-6"`) para fijar un modelo específico o para usar un modelo más pequeño para agentes más rápidos y económicos. Vea [modelos](https://platform.claude.com/docs/en/about-claude/models) para IDs disponibles.

197

198## La ventana de contexto

199

200La ventana de contexto es la cantidad total de información disponible para Claude durante una sesión. No se reinicia entre turnos dentro de una sesión. Todo se acumula: el prompt del sistema, definiciones de herramientas, historial de conversación, entradas de herramientas y salidas de herramientas. El contenido que permanece igual en todos los turnos (prompt del sistema, definiciones de herramientas, CLAUDE.md) se [almacena automáticamente en caché de prompt](https://platform.claude.com/docs/en/build-with-claude/prompt-caching), lo que reduce el costo y la latencia para prefijos repetidos.

201

202### Qué consume contexto

203

204Aquí está cómo cada componente afecta el contexto en el SDK:

205

206| Fuente | Cuándo se carga | Impacto |

207| :------------------------------- | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

208| **Prompt del sistema** | Cada solicitud | Costo fijo pequeño, siempre presente |

209| **Archivos CLAUDE.md** | Inicio de sesión, a través de [`settingSources`](/es/agent-sdk/claude-code-features) | Contenido completo en cada solicitud (pero almacenado en caché de prompt, así que solo la primera solicitud paga el costo completo) |

210| **Definiciones de herramientas** | Cada solicitud | Cada herramienta agrega su esquema; use [búsqueda de herramientas MCP](/es/agent-sdk/mcp#mcp-tool-search) para cargar herramientas bajo demanda en lugar de todas a la vez |

211| **Historial de conversación** | Se acumula en turnos | Crece con cada turno: prompts, respuestas, entradas de herramientas, salidas de herramientas |

212| **Descripciones de skills** | Inicio de sesión, a través de fuentes de configuración | Resúmenes cortos; el contenido completo se carga solo cuando se invoca |

213

214Las salidas de herramientas grandes consumen contexto significativo. Leer un archivo grande o ejecutar un comando con salida detallada puede usar miles de tokens en un solo turno. El contexto se acumula en turnos, así que sesiones más largas con muchas llamadas de herramientas acumulan significativamente más contexto que las cortas.

215

216### Compactación automática

217

218Cuando la ventana de contexto se acerca a su límite, el SDK compacta automáticamente la conversación: resume el historial anterior para liberar espacio, manteniendo intactos sus intercambios más recientes y decisiones clave. El SDK emite un mensaje con `type: "system"` y `subtype: "compact_boundary"` en el flujo cuando esto sucede (en Python esto es un `SystemMessage`; en TypeScript es un tipo separado `SDKCompactBoundaryMessage`).

219

220La compactación reemplaza mensajes anteriores con un resumen, así que instrucciones específicas del inicio de la conversación pueden no preservarse. Las reglas persistentes pertenecen a CLAUDE.md (cargado a través de [`settingSources`](/es/agent-sdk/claude-code-features)) en lugar de en el prompt inicial, porque el contenido de CLAUDE.md se reinyecta en cada solicitud.

221

222Puede personalizar el comportamiento de compactación de varias maneras:

223

224* **Instrucciones de resumen en CLAUDE.md:** El compactador lee su CLAUDE.md como cualquier otro contexto, así que puede incluir una sección diciéndole qué preservar al resumir. El encabezado de la sección es de forma libre (no una cadena mágica); el compactador coincide en intención.

225* **Hook `PreCompact`:** Ejecute lógica personalizada antes de que ocurra la compactación, por ejemplo para archivar la transcripción completa. El hook recibe un campo `trigger` (`manual` o `auto`). Vea [hooks](/es/agent-sdk/hooks).

226* **Compactación manual:** Envíe `/compact` como una cadena de prompt para activar la compactación bajo demanda. (Los slash commands enviados de esta manera son entradas de SDK, no atajos solo de CLI. Vea [slash commands en el SDK](/es/agent-sdk/slash-commands).)

227

228<Accordion title="Ejemplo: Instrucciones de resumen en CLAUDE.md">

229 Agregue una sección al CLAUDE.md de su proyecto diciéndole al compactador qué preservar. El nombre del encabezado no es especial; use cualquier etiqueta clara.

230

231 ```markdown CLAUDE.md theme={null}

232 # Summary instructions

233

234 When summarizing this conversation, always preserve:

235 - The current task objective and acceptance criteria

236 - File paths that have been read or modified

237 - Test results and error messages

238 - Decisions made and the reasoning behind them

239 ```

240</Accordion>

241

242### Mantener el contexto eficiente

243

244Algunas estrategias para agentes de larga duración:

245

246* **Use subagentes para subtareas.** Cada subagente comienza con una conversación nueva (sin historial de mensajes anterior, aunque carga su propio prompt del sistema y contexto a nivel de proyecto como CLAUDE.md). No ve los turnos del padre, y solo su respuesta final regresa al padre como resultado de herramienta. El contexto del agente principal crece por ese resumen, no por la transcripción completa de subtarea. Vea [Qué heredan los subagentes](/es/agent-sdk/subagents#what-subagents-inherit) para detalles.

247* **Sea selectivo con herramientas.** Cada definición de herramienta toma espacio de contexto. Use el campo `tools` en [`AgentDefinition`](/es/agent-sdk/subagents#agentdefinition-configuration) para limitar subagentes al conjunto mínimo que necesitan, y use [búsqueda de herramientas MCP](/es/agent-sdk/mcp#mcp-tool-search) para cargar herramientas bajo demanda en lugar de precargarlas todas.

248* **Observe costos de servidor MCP.** Cada servidor MCP agrega todos sus esquemas de herramientas a cada solicitud. Algunos servidores con muchas herramientas pueden consumir contexto significativo antes de que el agente haga ningún trabajo. La herramienta `ToolSearch` puede ayudar cargando herramientas bajo demanda en lugar de precargarlas todas. Vea [búsqueda de herramientas MCP](/es/agent-sdk/mcp#mcp-tool-search) para configuración.

249* **Use esfuerzo más bajo para tareas rutinarias.** Establezca [esfuerzo](#effort-level) a `"low"` para agentes que solo necesitan leer archivos o listar directorios. Esto reduce el uso de tokens y el costo.

250

251Para un desglose detallado de costos de contexto por característica, vea [Entender costos de contexto](/es/features-overview#understand-context-costs).

252

253## Sesiones y continuidad

254

255Cada interacción con el SDK crea o continúa una sesión. Capture el ID de sesión de `ResultMessage.session_id` (disponible en ambos SDK) para reanudar más tarde. El SDK de TypeScript también lo expone como un campo directo en el `SystemMessage` de init; en Python está anidado en `SystemMessage.data`.

256

257Cuando reanuda, el contexto completo de turnos anteriores se restaura: archivos que fueron leídos, análisis que fue realizado y acciones que fueron tomadas. También puede bifurcar una sesión para ramificarse en un enfoque diferente sin modificar el original.

258

259Vea [Gestión de sesiones](/es/agent-sdk/sessions) para la guía completa en patrones de reanudar, continuar y bifurcar.

260

261<Note>

262 En Python, `ClaudeSDKClient` maneja IDs de sesión automáticamente en múltiples llamadas. Vea la [referencia del SDK de Python](/es/agent-sdk/python#choosing-between-query-and-claudesdkclient) para detalles.

263</Note>

264

265## Manejar el resultado

266

267Cuando el bucle termina, el `ResultMessage` le dice qué sucedió y le proporciona la salida. El campo `subtype` (disponible en ambos SDK) es la forma principal de verificar el estado de terminación.

268

269| Subtipo de resultado | Qué sucedió | ¿Campo `result` disponible? |

270| :------------------------------------ | :-------------------------------------------------------------------------------------- | :-------------------------: |

271| `success` | Claude terminó la tarea normalmente | Sí |

272| `error_max_turns` | Alcanzó el límite de `maxTurns` antes de terminar | No |

273| `error_max_budget_usd` | Alcanzó el límite de `maxBudgetUsd` antes de terminar | No |

274| `error_during_execution` | Un error interrumpió el bucle (por ejemplo, una falla de API o solicitud cancelada) | No |

275| `error_max_structured_output_retries` | La validación de salida estructurada falló después del límite de reintentos configurado | No |

276

277El campo `result` (la salida de texto final) solo está presente en la variante `success`, así que siempre verifique el subtipo antes de leerlo. Todos los subtipos de resultado llevan `total_cost_usd`, `usage`, `num_turns` e `session_id` para que pueda rastrear el costo y reanudar incluso después de errores. En Python, `total_cost_usd` y `usage` se escriben como opcionales y pueden ser `None` en algunas rutas de error, así que proteja antes de formatearlos. Vea [Rastrear costos y uso](/es/agent-sdk/cost-tracking) para detalles sobre la interpretación de los campos `usage`.

278

279El resultado también incluye un campo `stop_reason` (`string | null` en TypeScript, `str | None` en Python) indicando por qué el modelo dejó de generar en su turno final. Los valores comunes son `end_turn` (modelo terminó normalmente), `max_tokens` (alcanzó el límite de token de salida) y `refusal` (el modelo rechazó la solicitud). En subtipos de resultado de error, `stop_reason` lleva el valor de la última respuesta de asistente antes de que el bucle terminara. Para detectar rechazos, verifique `stop_reason === "refusal"` (TypeScript) o `stop_reason == "refusal"` (Python). Vea [`SDKResultMessage`](/es/agent-sdk/typescript#sdkresultmessage) (TypeScript) o [`ResultMessage`](/es/agent-sdk/python#resultmessage) (Python) para el tipo completo.

280

281## Hooks

282

283[Hooks](/es/agent-sdk/hooks) son devoluciones de llamada que se disparan en puntos específicos del bucle: antes de que se ejecute una herramienta, después de que regresa, cuando el agente termina, y así sucesivamente. Algunos hooks comúnmente usados son:

284

285| Hook | Cuándo se dispara | Usos comunes |

286| :------------------------------- | :------------------------------------------ | :------------------------------------------------ |

287| `PreToolUse` | Antes de que se ejecute una herramienta | Validar entradas, bloquear comandos peligrosos |

288| `PostToolUse` | Después de que regresa una herramienta | Auditar salidas, activar efectos secundarios |

289| `UserPromptSubmit` | Cuando se envía un prompt | Inyectar contexto adicional en prompts |

290| `Stop` | Cuando el agente termina | Validar el resultado, guardar estado de sesión |

291| `SubagentStart` / `SubagentStop` | Cuando se genera un subagente o se completa | Rastrear y agregar resultados de tareas paralelas |

292| `PreCompact` | Antes de la compactación de contexto | Archivar transcripción completa antes de resumir |

293

294Los hooks se ejecutan en su proceso de aplicación, no dentro de la ventana de contexto del agente, así que no consumen contexto. Los hooks también pueden cortocircuitar el bucle: un hook `PreToolUse` que rechaza una llamada de herramienta evita que se ejecute, y Claude recibe el mensaje de rechazo en su lugar.

295

296Ambos SDK soportan todos los eventos anteriores. El SDK de TypeScript incluye eventos adicionales que Python aún no soporta. Vea [Controlar ejecución con hooks](/es/agent-sdk/hooks) para la lista completa de eventos, disponibilidad por SDK y la API de devolución de llamada completa.

297

298## Ponerlo todo junto

299

300Este ejemplo combina los conceptos clave de esta página en un único agente que arregla pruebas fallidas. Configura el agente con herramientas permitidas (aprobadas automáticamente para que el agente se ejecute autónomamente), configuración del proyecto y límites de seguridad en turnos y esfuerzo de razonamiento. A medida que se ejecuta el bucle, captura el ID de sesión para posible reanudación, maneja el resultado final e imprime el costo total.

301

302<CodeGroup>

303 ```python Python theme={null}

304 import asyncio

305 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

306

307

308 async def run_agent():

309 session_id = None

310

311 async for message in query(

312 prompt="Find and fix the bug causing test failures in the auth module",

313 options=ClaudeAgentOptions(

314 allowed_tools=[

315 "Read",

316 "Edit",

317 "Bash",

318 "Glob",

319 "Grep",

320 ], # Listing tools here auto-approves them (no prompting)

321 setting_sources=[

322 "project"

323 ], # Load CLAUDE.md, skills, hooks from current directory

324 max_turns=30, # Prevent runaway sessions

325 effort="high", # Thorough reasoning for complex debugging

326 ),

327 ):

328 # Handle the final result

329 if isinstance(message, ResultMessage):

330 session_id = message.session_id # Save for potential resumption

331

332 if message.subtype == "success":

333 print(f"Done: {message.result}")

334 elif message.subtype == "error_max_turns":

335 # Agent ran out of turns. Resume with a higher limit.

336 print(f"Hit turn limit. Resume session {session_id} to continue.")

337 elif message.subtype == "error_max_budget_usd":

338 print("Hit budget limit.")

339 else:

340 print(f"Stopped: {message.subtype}")

341 if message.total_cost_usd is not None:

342 print(f"Cost: ${message.total_cost_usd:.4f}")

343

344

345 asyncio.run(run_agent())

346 ```

347

348 ```typescript TypeScript theme={null}

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

350

351 let sessionId: string | undefined;

352

353 for await (const message of query({

354 prompt: "Find and fix the bug causing test failures in the auth module",

355 options: {

356 allowedTools: ["Read", "Edit", "Bash", "Glob", "Grep"], // Listing tools here auto-approves them (no prompting)

357 settingSources: ["project"], // Load CLAUDE.md, skills, hooks from current directory

358 maxTurns: 30, // Prevent runaway sessions

359 effort: "high" // Thorough reasoning for complex debugging

360 }

361 })) {

362 // Save the session ID to resume later if needed

363 if (message.type === "system" && message.subtype === "init") {

364 sessionId = message.session_id;

365 }

366

367 // Handle the final result

368 if (message.type === "result") {

369 if (message.subtype === "success") {

370 console.log(`Done: ${message.result}`);

371 } else if (message.subtype === "error_max_turns") {

372 // Agent ran out of turns. Resume with a higher limit.

373 console.log(`Hit turn limit. Resume session ${sessionId} to continue.`);

374 } else if (message.subtype === "error_max_budget_usd") {

375 console.log("Hit budget limit.");

376 } else {

377 console.log(`Stopped: ${message.subtype}`);

378 }

379 console.log(`Cost: $${message.total_cost_usd.toFixed(4)}`);

380 }

381 }

382 ```

383</CodeGroup>

384

385## Próximos pasos

386

387Ahora que entiende el bucle, aquí está dónde ir dependiendo de lo que esté construyendo:

388

389* **¿Aún no ha ejecutado un agente?** Comience con el [inicio rápido](/es/agent-sdk/quickstart) para obtener el SDK instalado y ver un ejemplo completo ejecutándose de principio a fin.

390* **¿Listo para conectarse a su proyecto?** [Cargue CLAUDE.md, skills y hooks del sistema de archivos](/es/agent-sdk/claude-code-features) para que el agente siga automáticamente las convenciones de su proyecto.

391* **¿Construyendo una interfaz de usuario interactiva?** Habilite [transmisión](/es/agent-sdk/streaming-output) para mostrar texto en vivo y llamadas de herramientas a medida que se ejecuta el bucle.

392* **¿Necesita control más ajustado sobre lo que el agente puede hacer?** Bloquee el acceso a herramientas con [permisos](/es/agent-sdk/permissions) y use [hooks](/es/agent-sdk/hooks) para auditar, bloquear o transformar llamadas de herramientas antes de que se ejecuten.

393* **¿Ejecutando tareas largas o costosas?** Descargue trabajo aislado a [subagentes](/es/agent-sdk/subagents) para mantener su contexto principal delgado.

394

395Para la imagen conceptual más amplia del bucle agente (no específica del SDK), vea [Cómo funciona Claude Code](/es/how-claude-code-works).

agent-sdk/hooks.md +11 −11

Details

236Su devolución de llamada devuelve un objeto con dos categorías de campos:236Su devolución de llamada devuelve un objeto con dos categorías de campos:

237 237

238* **Campos de nivel superior** controlan la conversación: `systemMessage` inyecta un mensaje en la conversación visible para el modelo, y `continue` (`continue_` en Python) determina si el agente sigue ejecutándose después de este hook.238* **Campos de nivel superior** controlan la conversación: `systemMessage` inyecta un mensaje en la conversación visible para el modelo, y `continue` (`continue_` en Python) determina si el agente sigue ejecutándose después de este hook.

239* **`hookSpecificOutput`** controla la operación actual. Los campos dentro dependen del tipo de evento de hook. Para hooks `PreToolUse`, aquí es donde establece `permissionDecision` (`"allow"`, `"deny"` o `"ask"`), `permissionDecisionReason` e `updatedInput`. En el SDK de TypeScript, `permissionDecision` también acepta `"defer"` para finalizar la consulta y [reanudar más tarde](/es/hooks#defer-a-tool-call-for-later); este valor no está disponible en el SDK de Python. Para hooks `PostToolUse`, puede establecer `additionalContext` para agregar información al resultado de la herramienta.239* **`hookSpecificOutput`** controla la operación actual. Los campos dentro dependen del tipo de evento de hook. Para hooks `PreToolUse`, aquí es donde establece `permissionDecision` (`"allow"`, `"deny"` o `"ask"`), `permissionDecisionReason` e `updatedInput`. En el SDK de TypeScript, `permissionDecision` también acepta `"defer"` para finalizar la consulta y [reanudar más tarde](/es/hooks#defer-a-tool-call-for-later); este valor no está disponible en el SDK de Python. Para hooks `PostToolUse`, puede establecer `additionalContext` para agregar información al resultado de la herramienta, o `updatedToolOutput` para reemplazar completamente la salida de la herramienta antes de que Claude la vea.

240 240

241Devuelva `{}` para permitir la operación sin cambios. Los hooks de devolución de llamada del SDK usan el mismo formato de salida JSON que [hooks de comandos de shell de Claude Code](/es/hooks#json-output), que documenta cada campo y opción específica del evento. Para las definiciones de tipo del SDK, vea las referencias del SDK de [TypeScript](/es/agent-sdk/typescript#sync-hook-json-output) y [Python](/es/agent-sdk/python#sync-hook-json-output).241Devuelva `{}` para permitir la operación sin cambios. Los hooks de devolución de llamada del SDK usan el mismo formato de salida JSON que [hooks de comandos de shell de Claude Code](/es/hooks#json-output), que documenta cada campo y opción específica del evento. Para las definiciones de tipo del SDK, vea las referencias del SDK de [TypeScript](/es/agent-sdk/typescript#sync-hook-json-output) y [Python](/es/agent-sdk/python#sync-hook-json-output).

242 242

417 ```417 ```

418</CodeGroup>418</CodeGroup>

419 419

420### Encadenar múltiples hooks420### Registrar múltiples hooks

421 421

422Los hooks se ejecutan en el orden en que aparecen en la matriz. Mantenga cada hook enfocado en una única responsabilidad y encadene múltiples hooks para lógica compleja:422Cuando se dispara un evento, todos los hooks coincidentes se ejecutan en paralelo. Para decisiones de permiso, el resultado más restrictivo gana: un único `deny` bloquea la llamada de herramienta independientemente de lo que devuelvan los otros hooks. Debido a que el orden de finalización es no determinista, escriba cada hook para actuar de forma independiente en lugar de depender de que otro hook se haya ejecutado primero.

423

424El ejemplo a continuación registra tres verificaciones independientes para cada llamada de herramienta:

423 425

424<CodeGroup>426<CodeGroup>

425 ```python Python theme={null}427 ```python Python theme={null}

426 options = ClaudeAgentOptions(428 options = ClaudeAgentOptions(

427 hooks={429 hooks={

428 "PreToolUse": [430 "PreToolUse": [

429 HookMatcher(hooks=[rate_limiter]), # First: check rate limits431 HookMatcher(hooks=[authorization_check]),

430 HookMatcher(hooks=[authorization_check]), # Second: verify permissions432 HookMatcher(hooks=[input_validator]),

431 HookMatcher(hooks=[input_sanitizer]), # Third: sanitize inputs433 HookMatcher(hooks=[audit_logger]),

432 HookMatcher(hooks=[audit_logger]), # Last: log the action

433 ]434 ]

434 }435 }

435 )436 )

439 const options = {440 const options = {

440 hooks: {441 hooks: {

441 PreToolUse: [442 PreToolUse: [

442 { hooks: [rateLimiter] }, // First: check rate limits443 { hooks: [authorizationCheck] },

443 { hooks: [authorizationCheck] }, // Second: verify permissions444 { hooks: [inputValidator] },

444 { hooks: [inputSanitizer] }, // Third: sanitize inputs445 { hooks: [auditLogger] }

445 { hooks: [auditLogger] } // Last: log the action

446 ]446 ]

447 }447 }

448 };448 };

agent-sdk/migration-guide.md +289 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Migrar a Claude Agent SDK

7> Guía para migrar los SDK de TypeScript y Python de Claude Code al Claude Agent SDK

9## Descripción general

11El SDK de Claude Code ha sido renombrado a **Claude Agent SDK** y su documentación ha sido reorganizada. Este cambio refleja las capacidades más amplias del SDK para construir agentes de IA más allá de solo tareas de codificación.

13## Qué ha cambiado

15| Aspecto | Anterior | Nuevo |

16| :-------------------------------- | :--------------------------- | :------------------------------- |

17| **Nombre del paquete (TS/JS)** | `@anthropic-ai/claude-code` | `@anthropic-ai/claude-agent-sdk` |

18| **Paquete de Python** | `claude-code-sdk` | `claude-agent-sdk` |

19| **Ubicación de la documentación** | Documentación de Claude Code | API Guide → Sección Agent SDK |

21<Note>

22 **Cambios en la documentación:** La documentación de Agent SDK se ha trasladado de la documentación de Claude Code a la Guía de API bajo una sección dedicada [Agent SDK](/es/agent-sdk/overview). La documentación de Claude Code ahora se enfoca en la herramienta CLI y características de automatización.

23</Note>

25## Pasos de migración

27### Para proyectos de TypeScript/JavaScript

29**1. Desinstale el paquete anterior:**

31```bash theme={null}

32npm uninstall @anthropic-ai/claude-code

33```

35**2. Instale el nuevo paquete:**

37```bash theme={null}

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

39```

41**3. Actualice sus importaciones:**

43Cambie todas las importaciones de `@anthropic-ai/claude-code` a `@anthropic-ai/claude-agent-sdk`:

45```typescript theme={null}

46// Antes

47import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-code";

49// Después

50import { query, tool, createSdkMcpServer } from "@anthropic-ai/claude-agent-sdk";

51```

53**4. Actualice las dependencias de package.json:**

55Si tiene el paquete listado en su `package.json`, actualícelo:

57Antes:

59```json theme={null}

60{

61 "dependencies": {

62 "@anthropic-ai/claude-code": "^0.0.42"

63 }

64}

65```

67Después:

69```json theme={null}

70{

71 "dependencies": {

72 "@anthropic-ai/claude-agent-sdk": "^0.2.0"

73 }

74}

75```

77¡Eso es todo! No se requieren otros cambios de código.

79### Para proyectos de Python

81**1. Desinstale el paquete anterior:**

83```bash theme={null}

84pip uninstall claude-code-sdk

85```

87**2. Instale el nuevo paquete:**

89```bash theme={null}

90pip install claude-agent-sdk

91```

93**3. Actualice sus importaciones:**

95Cambie todas las importaciones de `claude_code_sdk` a `claude_agent_sdk`:

97```python theme={null}

98# Antes

99from claude_code_sdk import query, ClaudeCodeOptions

100

101# Después

102from claude_agent_sdk import query, ClaudeAgentOptions

103```

104

105**4. Actualice los nombres de tipos:**

106

107Cambie `ClaudeCodeOptions` a `ClaudeAgentOptions`:

108

109```python theme={null}

110# Antes

111from claude_code_sdk import query, ClaudeCodeOptions

112

113options = ClaudeCodeOptions(model="claude-opus-4-7")

114

115# Después

116from claude_agent_sdk import query, ClaudeAgentOptions

117

118options = ClaudeAgentOptions(model="claude-opus-4-7")

119```

120

121**5. Revise [cambios importantes](#breaking-changes)**

122

123Realice los cambios de código necesarios para completar la migración.

124

125## Cambios importantes

126

127<Warning>

128 Para mejorar el aislamiento y la configuración explícita, Claude Agent SDK v0.1.0 introduce cambios importantes para los usuarios que migran desde Claude Code SDK. Revise esta sección cuidadosamente antes de migrar.

129</Warning>

130

131### Python: ClaudeCodeOptions renombrado a ClaudeAgentOptions

132

133**Qué cambió:** El tipo de SDK de Python `ClaudeCodeOptions` ha sido renombrado a `ClaudeAgentOptions`.

134

135**Migración:**

136

137```python theme={null}

138# ANTES (claude-code-sdk)

139from claude_code_sdk import query, ClaudeCodeOptions

140

141options = ClaudeCodeOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

142

143# DESPUÉS (claude-agent-sdk)

144from claude_agent_sdk import query, ClaudeAgentOptions

145

146options = ClaudeAgentOptions(model="claude-opus-4-7", permission_mode="acceptEdits")

147```

148

149**Por qué cambió:** El nombre del tipo ahora coincide con la marca "Claude Agent SDK" y proporciona consistencia en las convenciones de nomenclatura del SDK.

150

151### El prompt del sistema ya no es predeterminado

152

153**Qué cambió:** El SDK ya no utiliza el prompt del sistema de Claude Code de forma predeterminada.

154

155**Migración:**

156

157<CodeGroup>

158 ```typescript TypeScript theme={null}

159 // ANTES (v0.0.x) - Utilizaba el prompt del sistema de Claude Code de forma predeterminada

160 const result = query({ prompt: "Hello" });

161

162 // DESPUÉS (v0.1.0) - Utiliza un prompt del sistema mínimo de forma predeterminada

163 // Para obtener el comportamiento anterior, solicite explícitamente el preset de Claude Code:

164 const result = query({

165 prompt: "Hello",

166 options: {

167 systemPrompt: { type: "preset", preset: "claude_code" }

168 }

169 });

170

171 // O use un prompt del sistema personalizado:

172 const result = query({

173 prompt: "Hello",

174 options: {

175 systemPrompt: "You are a helpful coding assistant"

176 }

177 });

178 ```

179

180 ```python Python theme={null}

181 # ANTES (v0.0.x) - Utilizaba el prompt del sistema de Claude Code de forma predeterminada

182 async for message in query(prompt="Hello"):

183 print(message)

184

185 # DESPUÉS (v0.1.0) - Utiliza un prompt del sistema mínimo de forma predeterminada

186 # Para obtener el comportamiento anterior, solicite explícitamente el preset de Claude Code:

187 from claude_agent_sdk import query, ClaudeAgentOptions

188

189 async for message in query(

190 prompt="Hello",

191 options=ClaudeAgentOptions(

192 system_prompt={"type": "preset", "preset": "claude_code"} # Utilice el preset

193 ),

194 ):

195 print(message)

196

197 # O use un prompt del sistema personalizado:

198 async for message in query(

199 prompt="Hello",

200 options=ClaudeAgentOptions(system_prompt="You are a helpful coding assistant"),

201 ):

202 print(message)

203 ```

204</CodeGroup>

205

206**Por qué cambió:** Proporciona mejor control y aislamiento para aplicaciones SDK. Ahora puede construir agentes con comportamiento personalizado sin heredar las instrucciones enfocadas en CLI de Claude Code.

207

208### Predeterminado de fuentes de configuración

209

210Este predeterminado fue brevemente cambiado en v0.1.0 y luego revertido, por lo que no se requiere acción de migración.

211

212**Comportamiento actual:** Omitir `settingSources` en `query()` carga la configuración del usuario, proyecto y sistema de archivos local, coincidiendo con la CLI. Esto incluye `~/.claude/settings.json`, `.claude/settings.json`, `.claude/settings.local.json`, archivos CLAUDE.md y comandos personalizados.

213

214Para ejecutar aislado de la configuración del sistema de archivos, pase una matriz vacía:

215

216<CodeGroup>

217 ```typescript TypeScript theme={null}

218 const result = query({

219 prompt: "Hello",

220 options: {

221 settingSources: [] // No se carga configuración del sistema de archivos

222 }

223 });

224

225 // O cargue solo fuentes específicas:

226 const result = query({

227 prompt: "Hello",

228 options: {

229 settingSources: ["project"] // Solo configuración del proyecto

230 }

231 });

232 ```

233

234 ```python Python theme={null}

235 from claude_agent_sdk import query, ClaudeAgentOptions

236

237 async for message in query(

238 prompt="Hello",

239 options=ClaudeAgentOptions(setting_sources=[]), # No se carga configuración del sistema de archivos

240 ):

241 print(message)

242

243 # O cargue solo fuentes específicas:

244 async for message in query(

245 prompt="Hello",

246 options=ClaudeAgentOptions(

247 setting_sources=["project"] # Solo configuración del proyecto

248 ),

249 ):

250 print(message)

251 ```

252</CodeGroup>

253

254El aislamiento es especialmente importante para canalizaciones CI/CD, aplicaciones implementadas, entornos de prueba y sistemas multiinquilino donde las personalizaciones locales no deben filtrarse.

255

256<Note>

257 SDK v0.1.0 brevemente predeterminó a ninguna configuración cargada; esto fue revertido en versiones posteriores. Python SDK 0.1.59 y anteriores trataban una lista vacía igual que omitir la opción, así que actualice antes de confiar en `setting_sources=[]`. Vea [Lo que settingSources no controla](/es/agent-sdk/claude-code-features#what-settingsources-does-not-control) para entradas que se leen incluso cuando `settingSources` es `[]`.

258</Note>

259

260## ¿Por qué el cambio de nombre?

261

262El SDK de Claude Code fue diseñado originalmente para tareas de codificación, pero ha evolucionado hacia un marco poderoso para construir todo tipo de agentes de IA. El nuevo nombre "Claude Agent SDK" refleja mejor sus capacidades:

263

264* Construir agentes empresariales (asistentes legales, asesores financieros, soporte al cliente)

265* Crear agentes de codificación especializados (bots SRE, revisores de seguridad, agentes de revisión de código)

266* Desarrollar agentes personalizados para cualquier dominio con uso de herramientas, integración MCP y más

267

268## Obtener ayuda

269

270Si encuentra algún problema durante la migración:

271

272**Para TypeScript/JavaScript:**

273

2741. Verifique que todas las importaciones se actualicen para usar `@anthropic-ai/claude-agent-sdk`

2752. Verifique que su package.json tenga el nuevo nombre de paquete

2763. Ejecute `npm install` para asegurar que las dependencias se actualicen

277

278**Para Python:**

279

2801. Verifique que todas las importaciones se actualicen para usar `claude_agent_sdk`

2812. Verifique que su requirements.txt o pyproject.toml tenga el nuevo nombre de paquete

2823. Ejecute `pip install claude-agent-sdk` para asegurar que el paquete esté instalado

283

284## Próximos pasos

285

286* Explore la [Descripción general de Agent SDK](/es/agent-sdk/overview) para aprender sobre las características disponibles

287* Consulte la [Referencia de SDK de TypeScript](/es/agent-sdk/typescript) para documentación detallada de la API

288* Revise la [Referencia de SDK de Python](/es/agent-sdk/python) para documentación específica de Python

289* Aprenda sobre [Herramientas personalizadas](/es/agent-sdk/custom-tools) e [Integración MCP](/es/agent-sdk/mcp)

agent-sdk/permissions.md +242 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Configurar permisos

7> Controle cómo su agente utiliza herramientas con modos de permiso, hooks y reglas declarativas de permitir/denegar.

9El SDK del Agente Claude proporciona controles de permisos para gestionar cómo Claude utiliza las herramientas. Utilice modos de permiso y reglas para definir qué está permitido automáticamente, y la devolución de llamada [`canUseTool`](/es/agent-sdk/user-input) para manejar todo lo demás en tiempo de ejecución.

11<Note>

12 Esta página cubre modos de permiso y reglas. Para crear flujos de aprobación interactivos donde los usuarios aprueban o deniegan solicitudes de herramientas en tiempo de ejecución, consulte [Manejar aprobaciones e entrada del usuario](/es/agent-sdk/user-input).

13</Note>

15## Cómo se evalúan los permisos

17Cuando Claude solicita una herramienta, el SDK verifica los permisos en este orden:

19<Steps>

20 <Step title="Hooks">

21 Ejecute [hooks](/es/agent-sdk/hooks) primero. Un hook puede denegar la llamada directamente o pasarla. Un hook que devuelve `allow` no omite las reglas de denegar y preguntar a continuación; esas se evalúan independientemente del resultado del hook.

22 </Step>

24 <Step title="Reglas de denegar">

25 Verifique las reglas `deny` (de `disallowed_tools` y [settings.json](/es/settings#permission-settings)). Si una regla de denegar coincide, la herramienta se bloquea, incluso en modo `bypassPermissions`.

26 </Step>

28 <Step title="Modo de permiso">

29 Aplique el [modo de permiso](#permission-modes) activo. `bypassPermissions` aprueba todo lo que llega a este paso. `acceptEdits` aprueba operaciones de archivo. Otros modos se descartan.

30 </Step>

32 <Step title="Reglas de permitir">

33 Verifique las reglas `allow` (de `allowed_tools` y settings.json). Si una regla coincide, la herramienta se aprueba.

34 </Step>

36 <Step title="Devolución de llamada canUseTool">

37 Si no se resuelve por ninguno de los anteriores, llame a su devolución de llamada [`canUseTool`](/es/agent-sdk/user-input) para una decisión. En modo `dontAsk`, este paso se omite y la herramienta se deniega.

38 </Step>

39</Steps>

41<img src="https://mintcdn.com/claude-code/FEspvVUyRuaWjm0s/images/agent-sdk/permissions-flow.svg?fit=max&auto=format&n=FEspvVUyRuaWjm0s&q=85&s=a1759b0cf4541281a9fdd8f5348228e8" alt="Diagrama de flujo de evaluación de permisos" width="920" height="260" data-path="images/agent-sdk/permissions-flow.svg" />

43Esta página se enfoca en **reglas de permitir y denegar** y **modos de permiso**. Para los otros pasos:

45* **Hooks:** ejecute código personalizado para permitir, denegar o modificar solicitudes de herramientas. Consulte [Controlar la ejecución con hooks](/es/agent-sdk/hooks).

46* **Devolución de llamada canUseTool:** solicite aprobación a los usuarios en tiempo de ejecución. Consulte [Manejar aprobaciones e entrada del usuario](/es/agent-sdk/user-input).

48## Reglas de permitir y denegar

50`allowed_tools` y `disallowed_tools` (TypeScript: `allowedTools` / `disallowedTools`) agregan entradas a las listas de reglas de permitir y denegar en el flujo de evaluación anterior. Controlan si una llamada de herramienta se aprueba, no si la herramienta está disponible para Claude.

52| Opción | Efecto |

53| :------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------- |

54| `allowed_tools=["Read", "Grep"]` | `Read` y `Grep` se aprueban automáticamente. Las herramientas no listadas aquí aún existen y se descartan al modo de permiso y `canUseTool`. |

55| `disallowed_tools=["Bash"]` | `Bash` siempre se deniega. Las reglas de denegar se verifican primero y se mantienen en cada modo de permiso, incluido `bypassPermissions`. |

57Para un agente bloqueado, empareje `allowedTools` con `permissionMode: "dontAsk"`. Las herramientas listadas se aprueban; cualquier otra cosa se deniega directamente en lugar de solicitar:

59```typescript theme={null}

60const options = {

61 allowedTools: ["Read", "Glob", "Grep"],

62 permissionMode: "dontAsk"

63};

64```

66<Warning>

67 **`allowed_tools` no restringe `bypassPermissions`.** `allowed_tools` solo pre-aprueba las herramientas que lista. Las herramientas no listadas no coinciden con ninguna regla de permitir y se descartan al modo de permiso, donde `bypassPermissions` las aprueba. Establecer `allowed_tools=["Read"]` junto con `permission_mode="bypassPermissions"` aún aprueba cada herramienta, incluidas `Bash`, `Write` y `Edit`. Si necesita `bypassPermissions` pero desea que herramientas específicas se bloqueen, use `disallowed_tools`.

68</Warning>

70También puede configurar reglas de permitir, denegar y preguntar de forma declarativa en `.claude/settings.json`. Estas reglas se leen cuando la fuente de configuración `project` está habilitada, que lo está para las opciones predeterminadas de `query()`. Si establece `setting_sources` (TypeScript: `settingSources`) explícitamente, incluya `"project"` para que se apliquen. Consulte [Configuración de permisos](/es/settings#permission-settings) para la sintaxis de reglas.

72## Modos de permiso

74Los modos de permiso proporcionan control global sobre cómo Claude utiliza las herramientas. Puede establecer el modo de permiso al llamar a `query()` o cambiarlo dinámicamente durante sesiones de transmisión.

76### Modos disponibles

78El SDK admite estos modos de permiso:

80| Modo | Descripción | Comportamiento de herramientas |

81| :----------------------- | :----------------------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

82| `default` | Comportamiento de permiso estándar | Sin aprobaciones automáticas; las herramientas no coincidentes activan su devolución de llamada `canUseTool` |

83| `dontAsk` | Denegar en lugar de solicitar | Cualquier cosa no pre-aprobada por `allowed_tools` o reglas se deniega; `canUseTool` nunca se llama |

84| `acceptEdits` | Auto-aceptar ediciones de archivo | Las ediciones de archivo y [operaciones del sistema de archivos](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) se aprueban automáticamente |

85| `bypassPermissions` | Omitir todas las verificaciones de permiso | Todas las herramientas se ejecutan sin solicitudes de permiso (usar con cuidado) |

86| `plan` | Modo de planificación | Las herramientas de solo lectura se ejecutan; Claude analiza y planifica sin editar sus archivos fuente |

87| `auto` (solo TypeScript) | Aprobaciones clasificadas por modelo | Un clasificador de modelo aprueba o deniega cada llamada de herramienta. Consulte [Modo Auto](/es/permission-modes#eliminate-prompts-with-auto-mode) para disponibilidad |

89<Warning>

90 **Herencia de subagentos:** Cuando el padre usa `bypassPermissions`, `acceptEdits` o `auto`, todos los subagentos heredan ese modo y no se puede anular por subagentos. Los subagentos pueden tener diferentes indicaciones del sistema y comportamiento menos restringido que su agente principal, por lo que heredar `bypassPermissions` les otorga acceso completo y autónomo al sistema sin solicitudes de aprobación.

91</Warning>

93### Establecer modo de permiso

95Puede establecer el modo de permiso una vez al iniciar una consulta, o cambiarlo dinámicamente mientras la sesión está activa.

97<Tabs>

98 <Tab title="En tiempo de consulta">

99 Pase `permission_mode` (Python) o `permissionMode` (TypeScript) al crear una consulta. Este modo se aplica para toda la sesión a menos que se cambie dinámicamente.

100

101 <CodeGroup>

102 ```python Python theme={null}

103 import asyncio

104 from claude_agent_sdk import query, ClaudeAgentOptions

105

106

107 async def main():

108 async for message in query(

109 prompt="Help me refactor this code",

110 options=ClaudeAgentOptions(

111 permission_mode="default", # Set the mode here

112 ),

113 ):

114 if hasattr(message, "result"):

115 print(message.result)

116

117

118 asyncio.run(main())

119 ```

120

121 ```typescript TypeScript theme={null}

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

123

124 async function main() {

125 for await (const message of query({

126 prompt: "Help me refactor this code",

127 options: {

128 permissionMode: "default" // Set the mode here

129 }

130 })) {

131 if ("result" in message) {

132 console.log(message.result);

133 }

134 }

135 }

136

137 main();

138 ```

139 </CodeGroup>

140 </Tab>

141

142 <Tab title="Durante la transmisión">

143 Llame a `set_permission_mode()` (Python) o `setPermissionMode()` (TypeScript) para cambiar el modo a mitad de sesión. El nuevo modo entra en vigor inmediatamente para todas las solicitudes de herramientas posteriores. Esto le permite comenzar restrictivo y flexibilizar los permisos a medida que aumenta la confianza, por ejemplo, cambiar a `acceptEdits` después de revisar el enfoque inicial de Claude.

144

145 <CodeGroup>

146 ```python Python theme={null}

147 import asyncio

148 from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions

149

150

151 async def main():

152 async with ClaudeSDKClient(

153 options=ClaudeAgentOptions(

154 permission_mode="default", # Start in default mode

155 )

156 ) as client:

157 await client.query("Help me refactor this code")

158

159 # Change mode dynamically mid-session

160 await client.set_permission_mode("acceptEdits")

161

162 # Process messages with the new permission mode

163 async for message in client.receive_response():

164 if hasattr(message, "result"):

165 print(message.result)

166

167

168 asyncio.run(main())

169 ```

170

171 ```typescript TypeScript theme={null}

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

173

174 async function main() {

175 const q = query({

176 prompt: "Help me refactor this code",

177 options: {

178 permissionMode: "default" // Start in default mode

179 }

180 });

181

182 // Change mode dynamically mid-session

183 await q.setPermissionMode("acceptEdits");

184

185 // Process messages with the new permission mode

186 for await (const message of q) {

187 if ("result" in message) {

188 console.log(message.result);

189 }

190 }

191 }

192

193 main();

194 ```

195 </CodeGroup>

196 </Tab>

197</Tabs>

198

199### Detalles del modo

200

201#### Modo de aceptar ediciones (`acceptEdits`)

202

203Auto-aprueba operaciones de archivo para que Claude pueda editar código sin solicitar. Otras herramientas (como comandos Bash que no son operaciones del sistema de archivos) aún requieren permisos normales.

204

205**Operaciones auto-aprobadas:**

206

207* Ediciones de archivo (herramientas Edit, Write)

208* Comandos del sistema de archivos: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`

209

210Ambos se aplican solo a rutas dentro del directorio de trabajo o `additionalDirectories`. Las rutas fuera de ese alcance y las escrituras en rutas protegidas aún solicitan.

211

212**Usar cuando:** confía en las ediciones de Claude y desea una iteración más rápida, como durante la creación de prototipos o cuando trabaja en un directorio aislado.

213

214#### Modo no preguntar (`dontAsk`)

215

216Convierte cualquier solicitud de permiso en una denegación. Las herramientas pre-aprobadas por `allowed_tools`, reglas de permitir de `settings.json` o un hook se ejecutan normalmente. Todo lo demás se deniega sin llamar a `canUseTool`.

217

218**Usar cuando:** desea una superficie de herramienta fija y explícita para un agente sin interfaz y prefiere una denegación dura sobre la dependencia silenciosa de que `canUseTool` esté ausente.

219

220#### Modo de omitir permisos (`bypassPermissions`)

221

222Auto-aprueba todos los usos de herramientas sin solicitudes. Los hooks aún se ejecutan y pueden bloquear operaciones si es necesario.

223

224<Warning>

225 Usar con extrema precaución. Claude tiene acceso completo al sistema en este modo. Solo use en entornos controlados donde confía en todas las operaciones posibles.

226

227 `allowed_tools` no restringe este modo. Cada herramienta se aprueba, no solo las que listó. Las reglas de denegar (`disallowed_tools`), reglas explícitas de `ask` y hooks se evalúan antes de la verificación del modo y aún pueden bloquear una herramienta.

228</Warning>

229

230#### Modo de planificación (`plan`)

231

232Restringe Claude a herramientas de solo lectura. Claude puede leer archivos y ejecutar comandos de shell de solo lectura para explorar la base de código pero no edita sus archivos fuente. Claude puede usar `AskUserQuestion` para aclarar requisitos antes de finalizar el plan. Consulte [Manejar aprobaciones e entrada del usuario](/es/agent-sdk/user-input#handle-clarifying-questions) para manejar estas solicitudes.

233

234**Usar cuando:** desea que Claude proponga cambios sin ejecutarlos, como durante la revisión de código o cuando necesita aprobar cambios antes de que se realicen.

235

236## Recursos relacionados

237

238Para los otros pasos en el flujo de evaluación de permisos:

239

240* [Manejar aprobaciones e entrada del usuario](/es/agent-sdk/user-input): solicitudes de aprobación interactivas y preguntas aclaratorias

241* [Guía de hooks](/es/agent-sdk/hooks): ejecute código personalizado en puntos clave del ciclo de vida del agente

242* [Reglas de permisos](/es/settings#permission-settings): reglas declarativas de permitir/denegar en `settings.json`

agent-sdk/python.md +38 −36

Details

113#### Parámetros113#### Parámetros

114 114

116| :------------- | :----------------------------------------------- | :------------------------------------------------------------------------------------------------------ |116| :------------- | :---------------------------------------------- | :------------------------------------------------------------------------------------------------------ |

117| `name` | `str` | Identificador único para la herramienta |117| `name` | `str` | Identificador único para la herramienta |

118| `description` | `str` | Descripción legible de lo que hace la herramienta |118| `description` | `str` | Descripción legible de lo que hace la herramienta |

121 121

122#### Opciones de esquema de entrada122#### Opciones de esquema de entrada

123 123

269| `cwd` | `str \| None` | Directorio de trabajo para la sesión |269| `cwd` | `str \| None` | Directorio de trabajo para la sesión |

270| `tag` | `str \| None` | Etiqueta de sesión establecida por el usuario (ver [`tag_session()`](#tag-session)) |270| `tag` | `str \| None` | Etiqueta de sesión establecida por el usuario (ver [`tag_session()`](#tag_session)) |

272 272

273#### Ejemplo273#### Ejemplo

345 345

346Devuelve [`SDKSessionInfo`](#return-type-sdk-session-info), o `None` si la sesión no se encuentra.346Devuelve [`SDKSessionInfo`](#return-type-sdksessioninfo), o `None` si la sesión no se encuentra.

347 347

348#### Ejemplo348#### Ejemplo

349 349

381 381

382#### Ejemplo382#### Ejemplo

383 383

384Renombre la sesión más reciente para que sea más fácil de encontrar más tarde. El nuevo título aparece en [`SDKSessionInfo.custom_title`](#return-type-sdk-session-info) en lecturas posteriores.384Renombre la sesión más reciente para que sea más fácil de encontrar más tarde. El nuevo título aparece en [`SDKSessionInfo.custom_title`](#return-type-sdksessioninfo) en lecturas posteriores.

385 385

386```python theme={null}386```python theme={null}

387from claude_agent_sdk import list_sessions, rename_session387from claude_agent_sdk import list_sessions, rename_session

478| `rewind_files(user_message_id)` | Restaurar archivos a su estado en el mensaje de usuario especificado. Requiere `enable_file_checkpointing=True`. Ver [File checkpointing](/es/agent-sdk/file-checkpointing) |478| `rewind_files(user_message_id)` | Restaurar archivos a su estado en el mensaje de usuario especificado. Requiere `enable_file_checkpointing=True`. Ver [File checkpointing](/es/agent-sdk/file-checkpointing) |

479| `get_mcp_status()` | Obtener el estado de todos los servidores MCP configurados. Devuelve [`McpStatusResponse`](#mcp-status-response) |479| `get_mcp_status()` | Obtener el estado de todos los servidores MCP configurados. Devuelve [`McpStatusResponse`](#mcpstatusresponse) |

481| `toggle_mcp_server(server_name, enabled)` | Habilitar o deshabilitar un servidor MCP a mitad de sesión. Deshabilitar elimina sus herramientas |481| `toggle_mcp_server(server_name, enabled)` | Habilitar o deshabilitar un servidor MCP a mitad de sesión. Deshabilitar elimina sus herramientas |

482| `stop_task(task_id)` | Detener una tarea de fondo en ejecución. Un [`TaskNotificationMessage`](#task-notification-message) con estado `"stopped"` sigue en el flujo de mensajes |482| `stop_task(task_id)` | Detener una tarea de fondo en ejecución. Un [`TaskNotificationMessage`](#tasknotificationmessage) con estado `"stopped"` sigue en el flujo de mensajes |

485 485

791 effort: Literal["low", "medium", "high", "max"] | None = None791 effort: Literal["low", "medium", "high", "max"] | None = None

792 enable_file_checkpointing: bool = False792 enable_file_checkpointing: bool = False

793 session_store: SessionStore | None = None793 session_store: SessionStore | None = None

794 session_store_flush: SessionStoreFlushMode = "batched"

794```795```

795 796

797| :---------------------------- | :------------------------------------------------------------------------------------- | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |798| :---------------------------- | :------------------------------------------------------------------------------------ | :--------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

798| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configuración de herramientas. Use `{"type": "preset", "preset": "claude_code"}` para las herramientas predeterminadas de Claude Code |799| `tools` | `list[str] \| ToolsPreset \| None` | `None` | Configuración de herramientas. Use `{"type": "preset", "preset": "claude_code"}` para las herramientas predeterminadas de Claude Code |

799| `allowed_tools` | `list[str]` | `[]` | Herramientas para aprobar automáticamente sin solicitar. Esto no restringe Claude solo a estas herramientas; las herramientas no listadas caen a través de `permission_mode` y `can_use_tool`. Use `disallowed_tools` para bloquear herramientas. Ver [Permissions](/es/agent-sdk/permissions#allow-and-deny-rules) |800| `allowed_tools` | `list[str]` | `[]` | Herramientas para aprobar automáticamente sin solicitar. Esto no restringe Claude solo a estas herramientas; las herramientas no listadas caen a través de `permission_mode` y `can_use_tool`. Use `disallowed_tools` para bloquear herramientas. Ver [Permissions](/es/agent-sdk/permissions#allow-and-deny-rules) |

800| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configuración de prompt del sistema. Pase una cadena para un prompt personalizado, o use `{"type": "preset", "preset": "claude_code"}` para el prompt del sistema de Claude Code. Agregue `"append"` para extender el preset |801| `system_prompt` | `str \| SystemPromptPreset \| None` | `None` | Configuración de prompt del sistema. Pase una cadena para un prompt personalizado, o use `{"type": "preset", "preset": "claude_code"}` para el prompt del sistema de Claude Code. Agregue `"append"` para extender el preset |

812| `output_format` | `dict[str, Any] \| None` | `None` | Formato de salida para respuestas estructuradas (por ejemplo, `{"type": "json_schema", "schema": {...}}`). Ver [Structured outputs](/es/agent-sdk/structured-outputs) para detalles |813| `output_format` | `dict[str, Any] \| None` | `None` | Formato de salida para respuestas estructuradas (por ejemplo, `{"type": "json_schema", "schema": {...}}`). Ver [Structured outputs](/es/agent-sdk/structured-outputs) para detalles |

814| `cwd` | `str \| Path \| None` | `None` | Directorio de trabajo actual |815| `cwd` | `str \| Path \| None` | `None` | Directorio de trabajo actual |

831| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Controlar qué configuración del sistema de archivos cargar. Pase `[]` para deshabilitar la configuración de usuario, proyecto y local. La configuración de política administrada se carga independientemente. Ver [Use Claude Code features](/es/agent-sdk/claude-code-features#what-settingsources-does-not-control) |832| `setting_sources` | `list[SettingSource] \| None` | `None` (CLI defaults: all sources) | Controlar qué configuración del sistema de archivos cargar. Pase `[]` para deshabilitar la configuración de usuario, proyecto y local. La configuración de política administrada se carga independientemente. Ver [Use Claude Code features](/es/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

835| `session_store` | [`SessionStore`](/es/agent-sdk/session-storage#the-session-store-interface) ` \| None` | `None` | Reflejar transcripciones de sesión a un backend externo para que cualquier host pueda reanudarlas. Ver [Persist sessions to external storage](/es/agent-sdk/session-storage) |836| `session_store` | [`SessionStore`](/es/agent-sdk/session-storage#the-sessionstore-interface) ` \| None` | `None` | Reflejar transcripciones de sesión a un backend externo para que cualquier host pueda reanudarlas. Ver [Persist sessions to external storage](/es/agent-sdk/session-storage) |

837| `session_store_flush` | `Literal["batched", "eager"]` | `"batched"` | Cuándo vaciar entradas de transcripción reflejadas a `session_store`. `"batched"` vacía una vez por turno o cuando el búfer se llena; `"eager"` activa un vaciado de fondo después de cada fotograma. Se ignora cuando `session_store` es `None` |

836 838

837### `OutputFormat`839### `OutputFormat`

838 840

1031| `maxTurns` | No | Número máximo de turnos agentes antes de que el agente se detenga |1033| `maxTurns` | No | Número máximo de turnos agentes antes de que el agente se detenga |

1032| `background` | No | Ejecutar este agente como una tarea de fondo no bloqueante cuando se invoca |1034| `background` | No | Ejecutar este agente como una tarea de fondo no bloqueante cuando se invoca |

1033| `effort` | No | Nivel de esfuerzo de razonamiento para este agente. Acepta un nivel nombrado o un entero |1035| `effort` | No | Nivel de esfuerzo de razonamiento para este agente. Acepta un nivel nombrado o un entero |

1034| `permissionMode` | No | Modo de permiso para la ejecución de herramientas dentro de este agente. Ver [`PermissionMode`](#permission-mode) |1036| `permissionMode` | No | Modo de permiso para la ejecución de herramientas dentro de este agente. Ver [`PermissionMode`](#permissionmode) |

1035 1037

1036<Note>1038<Note>

1037 Los nombres de campo de `AgentDefinition` usan camelCase, como `disallowedTools`, `permissionMode` y `maxTurns`. Estos nombres se asignan directamente al formato de cable compartido con el SDK de TypeScript. Esto difiere de `ClaudeAgentOptions`, que usa snake\_case de Python para campos de nivel superior equivalentes como `disallowed_tools` y `permission_mode`. Porque `AgentDefinition` es una dataclass, pasar una palabra clave snake\_case genera un `TypeError` en el tiempo de construcción.1039 Los nombres de campo de `AgentDefinition` usan camelCase, como `disallowedTools`, `permissionMode` y `maxTurns`. Estos nombres se asignan directamente al formato de cable compartido con el SDK de TypeScript. Esto difiere de `ClaudeAgentOptions`, que usa snake\_case de Python para campos de nivel superior equivalentes como `disallowed_tools` y `permission_mode`. Porque `AgentDefinition` es una dataclass, pasar una palabra clave snake\_case genera un `TypeError` en el tiempo de construcción.

1045PermissionMode = Literal[1047PermissionMode = Literal[

1046 "default", # Standard permission behavior1048 "default", # Standard permission behavior

1047 "acceptEdits", # Auto-accept file edits1049 "acceptEdits", # Auto-accept file edits

1048 "plan", # Planning mode - no execution1050 "plan", # Planning mode - read-only tools only

1049 "dontAsk", # Deny anything not pre-approved instead of prompting1051 "dontAsk", # Deny anything not pre-approved instead of prompting

1050 "bypassPermissions", # Bypass all permission checks (use with caution)1052 "bypassPermissions", # Bypass all permission checks (use with caution)

1051]1053]

1081```1083```

1082 1084

1084| :------------ | :----------------------- | :----------------------------------------------- |1086| :------------ | :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1086| `suggestions` | `list[PermissionUpdate]` | Sugerencias de actualización de permiso del CLI |1088| `suggestions` | `list[PermissionUpdate]` | Sugerencias de actualización de permiso del CLI. Los prompts de Bash incluyen una sugerencia con el destino `localSettings`, por lo que devolverla en `updated_permissions` escribe la regla en `.claude/settings.local.json` y persiste en sesiones. |

1087 1089

1088### `PermissionResult`1090### `PermissionResult`

1089 1091

1289 1291

1290### `McpServerStatusConfig`1292### `McpServerStatusConfig`

1291 1293

1292La configuración de un servidor MCP como se reporta por [`get_mcp_status()`](#methods). Esta es la unión de todas las variantes de transporte [`McpServerConfig`](#mcp-server-config) más una variante de salida única `claudeai-proxy` para servidores proxied a través de claude.ai.1294La configuración de un servidor MCP como se reporta por [`get_mcp_status()`](#methods). Esta es la unión de todas las variantes de transporte [`McpServerConfig`](#mcpserverconfig) más una variante de salida única `claudeai-proxy` para servidores proxied a través de claude.ai.

1293 1295

1294```python theme={null}1296```python theme={null}

1295McpServerStatusConfig = (1297McpServerStatusConfig = (

1301)1303)

1302```1304```

1303 1305

1304`McpSdkServerConfigStatus` es la forma serializable de [`McpSdkServerConfig`](#mcp-sdk-server-config) con solo campos `type` (`"sdk"`) y `name` (`str`); la `instance` en proceso se omite. `McpClaudeAIProxyServerConfig` tiene campos `type` (`"claudeai-proxy"`), `url` (`str`), e `id` (`str`).1306`McpSdkServerConfigStatus` es la forma serializable de [`McpSdkServerConfig`](#mcpsdkserverconfig) con solo campos `type` (`"sdk"`) y `name` (`str`); la `instance` en proceso se omite. `McpClaudeAIProxyServerConfig` tiene campos `type` (`"claudeai-proxy"`), `url` (`str`), e `id` (`str`).

1305 1307

1306### `McpStatusResponse`1308### `McpStatusResponse`

1307 1309

1314 1316

1315### `McpServerStatus`1317### `McpServerStatus`

1316 1318

1317Estado de un servidor MCP conectado, contenido en [`McpStatusResponse`](#mcp-status-response).1319Estado de un servidor MCP conectado, contenido en [`McpStatusResponse`](#mcpstatusresponse).

1318 1320

1319```python theme={null}1321```python theme={null}

1320class McpServerStatus(TypedDict):1322class McpServerStatus(TypedDict):

1328```1330```

1329 1331

1331| :----------- | :-------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |1333| :----------- | :----------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1332| `name` | `str` | Nombre del servidor |1334| `name` | `str` | Nombre del servidor |

1333| `status` | `str` | Uno de `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, o `"disabled"` |1335| `status` | `str` | Uno de `"connected"`, `"failed"`, `"needs-auth"`, `"pending"`, o `"disabled"` |

1334| `serverInfo` | `dict` (opcional) | Nombre y versión del servidor (`{"name": str, "version": str}`) |1336| `serverInfo` | `dict` (opcional) | Nombre y versión del servidor (`{"name": str, "version": str}`) |

1336| `config` | [`McpServerStatusConfig`](#mcp-server-status-config) (opcional) | Configuración del servidor. Misma forma que [`McpServerConfig`](#mcp-server-config) (stdio, SSE, HTTP, o SDK), más una variante `claudeai-proxy` para servidores conectados a través de claude.ai |1338| `config` | [`McpServerStatusConfig`](#mcpserverstatusconfig) (opcional) | Configuración del servidor. Misma forma que [`McpServerConfig`](#mcpserverconfig) (stdio, SSE, HTTP, o SDK), más una variante `claudeai-proxy` para servidores conectados a través de claude.ai |

1339 1341

1416```1418```

1417 1419

1419| :------------------- | :------------------------------------------------------------- | :------------------------------------------------------------------------------------ |1421| :------------------- | :----------------------------------------------------------- | :----------------------------------------------------------------------------------- |

1421| `model` | `str` | Modelo que generó la respuesta |1423| `model` | `str` | Modelo que generó la respuesta |

1426 1428

1427### `AssistantMessageError`1429### `AssistantMessageError`

1481| `cache_creation_input_tokens` | `int` | Tokens usados para crear nuevas entradas de caché. |1483| `cache_creation_input_tokens` | `int` | Tokens usados para crear nuevas entradas de caché. |

1482| `cache_read_input_tokens` | `int` | Tokens leídos de entradas de caché existentes. |1484| `cache_read_input_tokens` | `int` | Tokens leídos de entradas de caché existentes. |

1483 1485

1484El dict `model_usage` asigna nombres de modelo a uso por modelo. Las claves del dict interno usan camelCase porque el valor se pasa sin modificar desde el proceso CLI subyacente, coincidiendo con el tipo [`ModelUsage`](/es/agent-sdk/typescript#model-usage) de TypeScript:1486El dict `model_usage` asigna nombres de modelo a uso por modelo. Las claves del dict interno usan camelCase porque el valor se pasa sin modificar desde el proceso CLI subyacente, coincidiendo con el tipo [`ModelUsage`](/es/agent-sdk/typescript#modelusage) de TypeScript:

1485 1487

1487| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |1489| -------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |

1490| `cacheReadInputTokens` | `int` | Tokens de lectura de caché para este modelo. |1492| `cacheReadInputTokens` | `int` | Tokens de lectura de caché para este modelo. |

1491| `cacheCreationInputTokens` | `int` | Tokens de creación de caché para este modelo. |1493| `cacheCreationInputTokens` | `int` | Tokens de creación de caché para este modelo. |

1492| `webSearchRequests` | `int` | Solicitudes de búsqueda web realizadas por este modelo. |1494| `webSearchRequests` | `int` | Solicitudes de búsqueda web realizadas por este modelo. |

1493| `costUSD` | `float` | Costo estimado en USD para este modelo, calculado del lado del cliente. Ver [Track cost and usage](/es/agent-sdk/cost-tracking) para advertencias de facturación. |1495| `costUSD` | `float` | Costo estimado en USD para este modelo, calculado del lado del cliente. Ver [Rastrear costo y uso](/es/agent-sdk/cost-tracking) para advertencias de facturación. |

1494| `contextWindow` | `int` | Tamaño de ventana de contexto para este modelo. |1496| `contextWindow` | `int` | Tamaño de ventana de contexto para este modelo. |

1495| `maxOutputTokens` | `int` | Límite de token de salida máximo para este modelo. |1497| `maxOutputTokens` | `int` | Límite de token de salida máximo para este modelo. |

1496 1498

1527```1529```

1528 1530

1530| :---------------- | :---------------------------------- | :------------------------------------ |1532| :---------------- | :-------------------------------- | :------------------------------------ |

1532| `uuid` | `str` | Identificador único del evento |1534| `uuid` | `str` | Identificador único del evento |

1533| `session_id` | `str` | Identificador de sesión |1535| `session_id` | `str` | Identificador de sesión |

1534 1536

1535### `RateLimitInfo`1537### `RateLimitInfo`

1536 1538

1537Estado del límite de velocidad llevado por [`RateLimitEvent`](#rate-limit-event).1539Estado del límite de velocidad llevado por [`RateLimitEvent`](#ratelimitevent).

1538 1540

1539```python theme={null}1541```python theme={null}

1540RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]1542RateLimitStatus = Literal["allowed", "allowed_warning", "rejected"]

1812 1814

1813Parámetros:1815Parámetros:

1814 1816

1815* `input`: Entrada de hook fuertemente tipada con uniones discriminadas basadas en `hook_event_name` (ver [`HookInput`](#hook-input))1817* `input`: Entrada de hook fuertemente tipada con uniones discriminadas basadas en `hook_event_name` (ver [`HookInput`](#hookinput))

1816* `tool_use_id`: Identificador de uso de herramienta opcional (para hooks relacionados con herramientas)1818* `tool_use_id`: Identificador de uso de herramienta opcional (para hooks relacionados con herramientas)

1817* `context`: Contexto de hook con información adicional1819* `context`: Contexto de hook con información adicional

1818 1820

1819Devuelve un [`HookJSONOutput`](#hook-json-output) que puede contener:1821Devuelve un [`HookJSONOutput`](#hookjsonoutput) que puede contener:

1820 1822

1821* `decision`: `"block"` para bloquear la acción1823* `decision`: `"block"` para bloquear la acción

1822* `systemMessage`: Mensaje del sistema a agregar a la transcripción1824* `systemMessage`: Mensaje del sistema a agregar a la transcripción

3109```3111```

3110 3112

3112| :-------------------------- | :------------------------------------------------------ | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |3114| :-------------------------- | :---------------------------------------------------- | :------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

3116| `allowUnsandboxedCommands` | `bool` | `True` | Permitir que el modelo solicite ejecutar comandos fuera del sandbox. Cuando es `True`, el modelo puede establecer `dangerouslyDisableSandbox` en entrada de herramienta, que vuelve al [sistema de permisos](#permissions-fallback-for-unsandboxed-commands) |3118| `allowUnsandboxedCommands` | `bool` | `True` | Permitir que el modelo solicite ejecutar comandos fuera del sandbox. Cuando es `True`, el modelo puede establecer `dangerouslyDisableSandbox` en entrada de herramienta, que vuelve al [sistema de permisos](#permissions-fallback-for-unsandboxed-commands) |

3120 3122

3121#### Ejemplo de uso3123#### Ejemplo de uso

agent-sdk/streaming-output.md +396 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Transmitir respuestas en tiempo real

7> Obtener respuestas en tiempo real del Agent SDK mientras el texto y las llamadas de herramientas se transmiten

9De forma predeterminada, el Agent SDK produce objetos `AssistantMessage` completos después de que Claude termina de generar cada respuesta. Para recibir actualizaciones incrementales mientras se generan texto y llamadas de herramientas, habilite la transmisión de mensajes parciales estableciendo `include_partial_messages` (Python) o `includePartialMessages` (TypeScript) en `true` en sus opciones.

11<Tip>

12 Esta página cubre la transmisión de salida (recibir tokens en tiempo real). Para modos de entrada (cómo envía mensajes), consulte [Enviar mensajes a agentes](/es/agent-sdk/streaming-vs-single-mode). También puede [transmitir respuestas usando el Agent SDK a través de la CLI](/es/headless).

13</Tip>

15## Habilitar la transmisión de salida

17Para habilitar la transmisión, establezca `include_partial_messages` (Python) o `includePartialMessages` (TypeScript) en `true` en sus opciones. Esto hace que el SDK produzca mensajes `StreamEvent` que contienen eventos de API sin procesar a medida que llegan, además de los `AssistantMessage` y `ResultMessage` habituales.

19Su código entonces necesita:

211. Verificar el tipo de cada mensaje para distinguir `StreamEvent` de otros tipos de mensaje

222. Para `StreamEvent`, extraer el campo `event` y verificar su `type`

233. Buscar eventos `content_block_delta` donde `delta.type` sea `text_delta`, que contienen los fragmentos de texto reales

25El ejemplo a continuación habilita la transmisión e imprime fragmentos de texto a medida que llegan. Observe las verificaciones de tipo anidadas: primero para `StreamEvent`, luego para `content_block_delta`, luego para `text_delta`:

27<CodeGroup>

28 ```python Python theme={null}

29 from claude_agent_sdk import query, ClaudeAgentOptions

30 from claude_agent_sdk.types import StreamEvent

31 import asyncio

34 async def stream_response():

35 options = ClaudeAgentOptions(

36 include_partial_messages=True,

37 allowed_tools=["Bash", "Read"],

38 )

40 async for message in query(prompt="List the files in my project", options=options):

41 if isinstance(message, StreamEvent):

42 event = message.event

43 if event.get("type") == "content_block_delta":

44 delta = event.get("delta", {})

45 if delta.get("type") == "text_delta":

46 print(delta.get("text", ""), end="", flush=True)

49 asyncio.run(stream_response())

50 ```

52 ```typescript TypeScript theme={null}

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

55 for await (const message of query({

56 prompt: "List the files in my project",

57 options: {

58 includePartialMessages: true,

59 allowedTools: ["Bash", "Read"]

60 }

61 })) {

62 if (message.type === "stream_event") {

63 const event = message.event;

64 if (event.type === "content_block_delta") {

65 if (event.delta.type === "text_delta") {

66 process.stdout.write(event.delta.text);

67 }

68 }

69 }

70 }

71 ```

72</CodeGroup>

74## Referencia de StreamEvent

76Cuando los mensajes parciales están habilitados, recibe eventos de transmisión de API de Claude sin procesar envueltos en un objeto. El tipo tiene nombres diferentes en cada SDK:

78* **Python**: `StreamEvent` (importar desde `claude_agent_sdk.types`)

79* **TypeScript**: `SDKPartialAssistantMessage` con `type: 'stream_event'`

81Ambos contienen eventos de API de Claude sin procesar, no texto acumulado. Necesita extraer y acumular deltas de texto usted mismo. Aquí está la estructura de cada tipo:

83<CodeGroup>

84 ```python Python theme={null}

85 @dataclass

86 class StreamEvent:

87 uuid: str # Unique identifier for this event

88 session_id: str # Session identifier

89 event: dict[str, Any] # The raw Claude API stream event

90 parent_tool_use_id: str | None # Parent tool ID if from a subagent

91 ```

93 ```typescript TypeScript theme={null}

94 type SDKPartialAssistantMessage = {

95 type: "stream_event";

96 event: BetaRawMessageStreamEvent; // From Anthropic SDK

97 parent_tool_use_id: string | null;

98 uuid: UUID;

99 session_id: string;

100 };

101 ```

102</CodeGroup>

103

104El campo `event` contiene el evento de transmisión sin procesar de la [API de Claude](https://platform.claude.com/docs/en/build-with-claude/streaming#event-types). Los tipos de eventos comunes incluyen:

105

106| Tipo de evento | Descripción |

107| :-------------------- | :------------------------------------------------------------------ |

108| `message_start` | Inicio de un nuevo mensaje |

109| `content_block_start` | Inicio de un nuevo bloque de contenido (texto o uso de herramienta) |

110| `content_block_delta` | Actualización incremental del contenido |

111| `content_block_stop` | Fin de un bloque de contenido |

112| `message_delta` | Actualizaciones a nivel de mensaje (razón de parada, uso) |

113| `message_stop` | Fin del mensaje |

114

115## Flujo de mensajes

116

117Con mensajes parciales habilitados, recibe mensajes en este orden:

118

119```text theme={null}

120StreamEvent (message_start)

121StreamEvent (content_block_start) - text block

122StreamEvent (content_block_delta) - text chunks...

123StreamEvent (content_block_stop)

124StreamEvent (content_block_start) - tool_use block

125StreamEvent (content_block_delta) - tool input chunks...

126StreamEvent (content_block_stop)

127StreamEvent (message_delta)

128StreamEvent (message_stop)

129AssistantMessage - complete message with all content

130... tool executes ...

131... more streaming events for next turn ...

132ResultMessage - final result

133```

134

135Sin mensajes parciales habilitados (`include_partial_messages` en Python, `includePartialMessages` en TypeScript), recibe todos los tipos de mensaje excepto `StreamEvent`. Los tipos comunes incluyen `SystemMessage` (inicialización de sesión), `AssistantMessage` (respuestas completas), `ResultMessage` (resultado final) y un mensaje de límite compacto que indica cuándo se compactó el historial de conversación (`SDKCompactBoundaryMessage` en TypeScript; `SystemMessage` con subtipo `"compact_boundary"` en Python).

136

137## Transmitir respuestas de texto

138

139Para mostrar texto a medida que se genera, busque eventos `content_block_delta` donde `delta.type` sea `text_delta`. Estos contienen los fragmentos de texto incrementales. El ejemplo a continuación imprime cada fragmento a medida que llega:

140

141<CodeGroup>

142 ```python Python theme={null}

143 from claude_agent_sdk import query, ClaudeAgentOptions

144 from claude_agent_sdk.types import StreamEvent

145 import asyncio

146

147

148 async def stream_text():

149 options = ClaudeAgentOptions(include_partial_messages=True)

150

151 async for message in query(prompt="Explain how databases work", options=options):

152 if isinstance(message, StreamEvent):

153 event = message.event

154 if event.get("type") == "content_block_delta":

155 delta = event.get("delta", {})

156 if delta.get("type") == "text_delta":

157 # Print each text chunk as it arrives

158 print(delta.get("text", ""), end="", flush=True)

159

160 print() # Final newline

161

162

163 asyncio.run(stream_text())

164 ```

165

166 ```typescript TypeScript theme={null}

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

168

169 for await (const message of query({

170 prompt: "Explain how databases work",

171 options: { includePartialMessages: true }

172 })) {

173 if (message.type === "stream_event") {

174 const event = message.event;

175 if (event.type === "content_block_delta" && event.delta.type === "text_delta") {

176 process.stdout.write(event.delta.text);

177 }

178 }

179 }

180

181 console.log(); // Final newline

182 ```

183</CodeGroup>

184

185## Transmitir llamadas de herramientas

186

187Las llamadas de herramientas también se transmiten incrementalmente. Puede rastrear cuándo comienzan las herramientas, recibir su entrada a medida que se genera y ver cuándo se completan. El ejemplo a continuación rastrea la herramienta actual que se está llamando y acumula la entrada JSON a medida que se transmite. Utiliza tres tipos de eventos:

188

189* `content_block_start`: la herramienta comienza

190* `content_block_delta` con `input_json_delta`: llegan fragmentos de entrada

191* `content_block_stop`: llamada de herramienta completada

192

193<CodeGroup>

194 ```python Python theme={null}

195 from claude_agent_sdk import query, ClaudeAgentOptions

196 from claude_agent_sdk.types import StreamEvent

197 import asyncio

198

199

200 async def stream_tool_calls():

201 options = ClaudeAgentOptions(

202 include_partial_messages=True,

203 allowed_tools=["Read", "Bash"],

204 )

205

206 # Track the current tool and accumulate its input JSON

207 current_tool = None

208 tool_input = ""

209

210 async for message in query(prompt="Read the README.md file", options=options):

211 if isinstance(message, StreamEvent):

212 event = message.event

213 event_type = event.get("type")

214

215 if event_type == "content_block_start":

216 # New tool call is starting

217 content_block = event.get("content_block", {})

218 if content_block.get("type") == "tool_use":

219 current_tool = content_block.get("name")

220 tool_input = ""

221 print(f"Starting tool: {current_tool}")

222

223 elif event_type == "content_block_delta":

224 delta = event.get("delta", {})

225 if delta.get("type") == "input_json_delta":

226 # Accumulate JSON input as it streams in

227 chunk = delta.get("partial_json", "")

228 tool_input += chunk

229 print(f" Input chunk: {chunk}")

230

231 elif event_type == "content_block_stop":

232 # Tool call complete - show final input

233 if current_tool:

234 print(f"Tool {current_tool} called with: {tool_input}")

235 current_tool = None

236

237

238 asyncio.run(stream_tool_calls())

239 ```

240

241 ```typescript TypeScript theme={null}

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

243

244 // Track the current tool and accumulate its input JSON

245 let currentTool: string | null = null;

246 let toolInput = "";

247

248 for await (const message of query({

249 prompt: "Read the README.md file",

250 options: {

251 includePartialMessages: true,

252 allowedTools: ["Read", "Bash"]

253 }

254 })) {

255 if (message.type === "stream_event") {

256 const event = message.event;

257

258 if (event.type === "content_block_start") {

259 // New tool call is starting

260 if (event.content_block.type === "tool_use") {

261 currentTool = event.content_block.name;

262 toolInput = "";

263 console.log(`Starting tool: ${currentTool}`);

264 }

265 } else if (event.type === "content_block_delta") {

266 if (event.delta.type === "input_json_delta") {

267 // Accumulate JSON input as it streams in

268 const chunk = event.delta.partial_json;

269 toolInput += chunk;

270 console.log(` Input chunk: ${chunk}`);

271 }

272 } else if (event.type === "content_block_stop") {

273 // Tool call complete - show final input

274 if (currentTool) {

275 console.log(`Tool ${currentTool} called with: ${toolInput}`);

276 currentTool = null;

277 }

278 }

279 }

280 }

281 ```

282</CodeGroup>

283

284## Construir una interfaz de usuario de transmisión

285

286Este ejemplo combina la transmisión de texto y herramientas en una interfaz de usuario coherente. Rastrea si el agente está ejecutando actualmente una herramienta (usando una bandera `in_tool`) para mostrar indicadores de estado como `[Using Read...]` mientras se ejecutan las herramientas. El texto se transmite normalmente cuando no está en una herramienta, y la finalización de la herramienta desencadena un mensaje "done". Este patrón es útil para interfaces de chat que necesitan mostrar progreso durante tareas de agente de varios pasos.

287

288<CodeGroup>

289 ```python Python theme={null}

290 from claude_agent_sdk import query, ClaudeAgentOptions, ResultMessage

291 from claude_agent_sdk.types import StreamEvent

292 import asyncio

293 import sys

294

295

296 async def streaming_ui():

297 options = ClaudeAgentOptions(

298 include_partial_messages=True,

299 allowed_tools=["Read", "Bash", "Grep"],

300 )

301

302 # Track whether we're currently in a tool call

303 in_tool = False

304

305 async for message in query(

306 prompt="Find all TODO comments in the codebase", options=options

307 ):

308 if isinstance(message, StreamEvent):

309 event = message.event

310 event_type = event.get("type")

311

312 if event_type == "content_block_start":

313 content_block = event.get("content_block", {})

314 if content_block.get("type") == "tool_use":

315 # Tool call is starting - show status indicator

316 tool_name = content_block.get("name")

317 print(f"\n[Using {tool_name}...]", end="", flush=True)

318 in_tool = True

319

320 elif event_type == "content_block_delta":

321 delta = event.get("delta", {})

322 # Only stream text when not executing a tool

323 if delta.get("type") == "text_delta" and not in_tool:

324 sys.stdout.write(delta.get("text", ""))

325 sys.stdout.flush()

326

327 elif event_type == "content_block_stop":

328 if in_tool:

329 # Tool call finished

330 print(" done", flush=True)

331 in_tool = False

332

333 elif isinstance(message, ResultMessage):

334 # Agent finished all work

335 print(f"\n\n--- Complete ---")

336

337

338 asyncio.run(streaming_ui())

339 ```

340

341 ```typescript TypeScript theme={null}

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

343

344 // Track whether we're currently in a tool call

345 let inTool = false;

346

347 for await (const message of query({

348 prompt: "Find all TODO comments in the codebase",

349 options: {

350 includePartialMessages: true,

351 allowedTools: ["Read", "Bash", "Grep"]

352 }

353 })) {

354 if (message.type === "stream_event") {

355 const event = message.event;

356

357 if (event.type === "content_block_start") {

358 if (event.content_block.type === "tool_use") {

359 // Tool call is starting - show status indicator

360 process.stdout.write(`\n[Using ${event.content_block.name}...]`);

361 inTool = true;

362 }

363 } else if (event.type === "content_block_delta") {

364 // Only stream text when not executing a tool

365 if (event.delta.type === "text_delta" && !inTool) {

366 process.stdout.write(event.delta.text);

367 }

368 } else if (event.type === "content_block_stop") {

369 if (inTool) {

370 // Tool call finished

371 console.log(" done");

372 inTool = false;

373 }

374 }

375 } else if (message.type === "result") {

376 // Agent finished all work

377 console.log("\n\n--- Complete ---");

378 }

379 }

380 ```

381</CodeGroup>

382

383## Limitaciones conocidas

384

385Algunas características del SDK son incompatibles con la transmisión:

386

387* **Extended thinking**: cuando establece explícitamente `max_thinking_tokens` (Python) o `maxThinkingTokens` (TypeScript), los mensajes `StreamEvent` no se emiten. Solo recibirá mensajes completos después de cada turno. Tenga en cuenta que el pensamiento está deshabilitado de forma predeterminada en el SDK, por lo que la transmisión funciona a menos que lo habilite.

388* **Structured output**: el resultado JSON aparece solo en el `ResultMessage.structured_output` final, no como deltas de transmisión. Consulte [structured outputs](/es/agent-sdk/structured-outputs) para obtener detalles.

389

390## Próximos pasos

391

392Ahora que puede transmitir texto y llamadas de herramientas en tiempo real, explore estos temas relacionados:

393

394* [Interactive vs one-shot queries](/es/agent-sdk/streaming-vs-single-mode): elija entre modos de entrada para su caso de uso

395* [Structured outputs](/es/agent-sdk/structured-outputs): obtenga respuestas JSON tipificadas del agente

396* [Permissions](/es/agent-sdk/permissions): controle qué herramientas puede usar el agente

agent-sdk/todo-tracking.md +189 −0 created

Details

1> ## Documentation Index

2> Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

3> Use this file to discover all available pages before exploring further.

5# Listas de Tareas

7> Rastrear y mostrar tareas pendientes utilizando el SDK del Agente Claude para la gestión organizada de tareas

9El seguimiento de tareas proporciona una forma estructurada de gestionar tareas y mostrar el progreso a los usuarios. El SDK del Agente Claude incluye funcionalidad de tareas integrada que ayuda a organizar flujos de trabajo complejos y mantener a los usuarios informados sobre la progresión de las tareas.

11### Ciclo de Vida de las Tareas

13Las tareas siguen un ciclo de vida predecible:

151. **Creadas** como `pending` cuando se identifican las tareas

162. **Activadas** a `in_progress` cuando comienza el trabajo

173. **Completadas** cuando la tarea finaliza exitosamente

184. **Eliminadas** cuando todas las tareas en un grupo se completan

20### Cuándo se Utilizan las Tareas

22El SDK crea automáticamente tareas para:

24* **Tareas complejas de múltiples pasos** que requieren 3 o más acciones distintas

25* **Listas de tareas proporcionadas por el usuario** cuando se mencionan múltiples elementos

26* **Operaciones no triviales** que se benefician del seguimiento del progreso

27* **Solicitudes explícitas** cuando los usuarios piden organización de tareas

29## Ejemplos

31### Monitoreo de Cambios en Tareas

33<CodeGroup>

34 ```typescript TypeScript theme={null}

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

37 for await (const message of query({

38 prompt: "Optimize my React app performance and track progress with todos",

39 options: { maxTurns: 15 }

40 })) {

41 // Todo updates are reflected in the message stream

42 if (message.type === "assistant") {

43 for (const block of message.message.content) {

44 if (block.type === "tool_use" && block.name === "TodoWrite") {

45 const todos = block.input.todos;

47 console.log("Todo Status Update:");

48 todos.forEach((todo, index) => {

49 const status =

50 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

51 console.log(`${index + 1}. ${status} ${todo.content}`);

52 });

53 }

54 }

55 }

56 }

57 ```

59 ```python Python theme={null}

60 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

62 async for message in query(

63 prompt="Optimize my React app performance and track progress with todos",

64 options=ClaudeAgentOptions(max_turns=15),

65 ):

66 # Todo updates are reflected in the message stream

67 if isinstance(message, AssistantMessage):

68 for block in message.content:

69 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

70 todos = block.input["todos"]

72 print("Todo Status Update:")

73 for i, todo in enumerate(todos):

74 status = (

75 "✅"

76 if todo["status"] == "completed"

77 else "🔧"

78 if todo["status"] == "in_progress"

79 else "❌"

80 )

81 print(f"{i + 1}. {status} {todo['content']}")

82 ```

83</CodeGroup>

85### Visualización de Progreso en Tiempo Real

87<CodeGroup>

88 ```typescript TypeScript theme={null}

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

91 class TodoTracker {

92 private todos: any[] = [];

94 displayProgress() {

95 if (this.todos.length === 0) return;

97 const completed = this.todos.filter((t) => t.status === "completed").length;

98 const inProgress = this.todos.filter((t) => t.status === "in_progress").length;

99 const total = this.todos.length;

100

101 console.log(`\nProgress: ${completed}/${total} completed`);

102 console.log(`Currently working on: ${inProgress} task(s)\n`);

103

104 this.todos.forEach((todo, index) => {

105 const icon =

106 todo.status === "completed" ? "✅" : todo.status === "in_progress" ? "🔧" : "❌";

107 const text = todo.status === "in_progress" ? todo.activeForm : todo.content;

108 console.log(`${index + 1}. ${icon} ${text}`);

109 });

110 }

111

112 async trackQuery(prompt: string) {

113 for await (const message of query({

114 prompt,

115 options: { maxTurns: 20 }

116 })) {

117 if (message.type === "assistant") {

118 for (const block of message.message.content) {

119 if (block.type === "tool_use" && block.name === "TodoWrite") {

120 this.todos = block.input.todos;

121 this.displayProgress();

122 }

123 }

124 }

125 }

126 }

127 }

128

129 // Usage

130 const tracker = new TodoTracker();

131 await tracker.trackQuery("Build a complete authentication system with todos");

132 ```

133

134 ```python Python theme={null}

135 from claude_agent_sdk import query, ClaudeAgentOptions, AssistantMessage, ToolUseBlock

136 from typing import List, Dict

137

138

139 class TodoTracker:

140 def __init__(self):

141 self.todos: List[Dict] = []

142

143 def display_progress(self):

144 if not self.todos:

145 return

146

147 completed = len([t for t in self.todos if t["status"] == "completed"])

148 in_progress = len([t for t in self.todos if t["status"] == "in_progress"])

149 total = len(self.todos)

150

151 print(f"\nProgress: {completed}/{total} completed")

152 print(f"Currently working on: {in_progress} task(s)\n")

153

154 for i, todo in enumerate(self.todos):

155 icon = (

156 "✅"

157 if todo["status"] == "completed"

158 else "🔧"

159 if todo["status"] == "in_progress"

160 else "❌"

161 )

162 text = (

163 todo["activeForm"]

164 if todo["status"] == "in_progress"

165 else todo["content"]

166 )

167 print(f"{i + 1}. {icon} {text}")

168

169 async def track_query(self, prompt: str):

170 async for message in query(prompt=prompt, options=ClaudeAgentOptions(max_turns=20)):

171 if isinstance(message, AssistantMessage):

172 for block in message.content:

173 if isinstance(block, ToolUseBlock) and block.name == "TodoWrite":

174 self.todos = block.input["todos"]

175 self.display_progress()

176

177

178 # Usage

179 tracker = TodoTracker()

180 await tracker.track_query("Build a complete authentication system with todos")

181 ```

182</CodeGroup>

183

184## Documentación Relacionada

185

186* [Referencia del SDK de TypeScript](/es/agent-sdk/typescript)

187* [Referencia del SDK de Python](/es/agent-sdk/python)

188* [Modo de Streaming vs Modo Único](/es/agent-sdk/streaming-vs-single-mode)

189* [Herramientas Personalizadas](/es/agent-sdk/custom-tools)

agent-sdk/typescript.md +31 −31

Details

41#### Parámetros41#### Parámetros

42 42

~~44| :-------- | :---------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |~~44| :-------- | :--------------------------------------------------------------- | :--------------------------------------------------------------------------------------- |

47 47

48#### Devuelve48#### Devuelve

49 49

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

51 51

52### `startup()`52### `startup()`

53 53

54Precalienta el subproceso CLI iniciándolo y completando el protocolo de inicialización antes de que un mensaje esté disponible. El identificador [`WarmQuery`](#warm-query) 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.54Precalienta 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.

55 55

56```typescript theme={null}56```typescript theme={null}

57function startup(params?: {57function startup(params?: {

69 69

70#### Devuelve70#### Devuelve

71 71

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

73 73

74#### Ejemplo74#### Ejemplo

75 75

104#### Parámetros104#### Parámetros

105 105

107| :------------ | :------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------------ |107| :------------ | :---------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ |

112| `extras` | `{ annotations?: `[`ToolAnnotations`](#tool-annotations)` }` | Anotaciones opcionales de herramienta MCP que proporcionan sugerencias de comportamiento a los clientes |112| `extras` | `{ annotations?: `[`ToolAnnotations`](#toolannotations)` }` | Anotaciones opcionales de herramienta MCP que proporcionan sugerencias de comportamiento a los clientes |

113 113

114#### `ToolAnnotations`114#### `ToolAnnotations`

115 115

191 191

192#### Ejemplo192#### Ejemplo

272 272

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

274 274

275### `renameSession()`275### `renameSession()`

276 276

328| `allowedTools` | `string[]` | `[]` | Herramientas para aprobar automáticamente sin solicitar. Esto no restringe Claude a solo estas herramientas; las herramientas no listadas caen en `permissionMode` y `canUseTool`. Use `disallowedTools` para bloquear herramientas. Vea [Permisos](/es/agent-sdk/permissions#allow-and-deny-rules) |328| `allowedTools` | `string[]` | `[]` | Herramientas para aprobar automáticamente sin solicitar. Esto no restringe Claude a solo estas herramientas; las herramientas no listadas caen en `permissionMode` y `canUseTool`. Use `disallowedTools` para bloquear herramientas. Vea [Permisos](/es/agent-sdk/permissions#allow-and-deny-rules) |

341| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionales |341| `extraArgs` | `Record<string, string \| null>` | `{}` | Argumentos adicionales |

344| `hooks` | `Partial<Record<`[`HookEvent`](#hook-event)`, `[`HookCallbackMatcher`](#hook-callback-matcher)`[]>>` | `{}` | Devoluciones de llamada de hooks para eventos |344| `hooks` | `Partial<Record<`[`HookEvent`](#hookevent)`, `[`HookCallbackMatcher`](#hookcallbackmatcher)`[]>>` | `{}` | Devoluciones de llamada de hooks para eventos |

346| `maxBudgetUsd` | `number` | `undefined` | Detenga la consulta cuando la estimación de costo del lado del cliente alcance este valor en USD. Comparado con la misma estimación que `total_cost_usd`; vea [Rastrear costo y uso](/es/agent-sdk/cost-tracking) para advertencias de precisión |346| `maxBudgetUsd` | `number` | `undefined` | Detenga la consulta cuando la estimación de costo del lado del cliente alcance este valor en USD. Comparado con la misma estimación que `total_cost_usd`; vea [Rastrear costo y uso](/es/agent-sdk/cost-tracking) para advertencias de precisión |

349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcp-server-config)>` | `{}` | Configuraciones de servidor MCP |349| `mcpServers` | `Record<string, [`McpServerConfig`](#mcpserverconfig)>` | `{}` | Configuraciones de servidor MCP |

351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Defina el formato de salida para los resultados del agente. Vea [Structured outputs](/es/agent-sdk/structured-outputs) para detalles |351| `outputFormat` | `{ type: 'json_schema', schema: JSONSchema }` | `undefined` | Defina el formato de salida para los resultados del agente. Vea [Structured outputs](/es/agent-sdk/structured-outputs) para detalles |

352| `pathToClaudeCodeExecutable` | `string` | Auto-resuelto desde el binario nativo incluido | Ruta al ejecutable de Claude Code. Solo se necesita si las dependencias opcionales se omitieron durante la instalación o su plataforma no está en el conjunto compatible |352| `pathToClaudeCodeExecutable` | `string` | Auto-resuelto desde el binario nativo incluido | Ruta al ejecutable de Claude Code. Solo se necesita si las dependencias opcionales se omitieron durante la instalación o su plataforma no está en el conjunto compatible |

362| `sessionStore` | [`SessionStore`](/es/agent-sdk/session-storage#the-session-store-interface) | `undefined` | Refleje transcripciones de sesión en un backend externo para que cualquier host pueda reanudarlas. Vea [Persistir sesiones en almacenamiento externo](/es/agent-sdk/session-storage) |362| `sessionStore` | [`SessionStore`](/es/agent-sdk/session-storage#the-sessionstore-interface) | `undefined` | Refleje transcripciones de sesión en un backend externo para que cualquier host pueda reanudarlas. Vea [Persistir sesiones en almacenamiento externo](/es/agent-sdk/session-storage) |

363| `settingSources` | [`SettingSource`](#setting-source)`[]` | Valores predeterminados de CLI (todas las fuentes) | Controle qué configuración del sistema de archivos cargar. Pase `[]` para deshabilitar la configuración de usuario, proyecto y local. La configuración de política administrada se carga independientemente. Vea [Usar características de Claude Code](/es/agent-sdk/claude-code-features#what-settingsources-does-not-control) |363| `settingSources` | [`SettingSource`](#settingsource)`[]` | Valores predeterminados de CLI (todas las fuentes) | Controle qué configuración del sistema de archivos cargar. Pase `[]` para deshabilitar la configuración de usuario, proyecto y local. La configuración de política administrada se carga independientemente. Vea [Usar características de Claude Code](/es/agent-sdk/claude-code-features#what-settingsources-does-not-control) |

364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Función personalizada para generar el proceso de Claude Code. Use para ejecutar Claude Code en máquinas virtuales, contenedores o entornos remotos |364| `spawnClaudeCodeProcess` | `(options: SpawnOptions) => SpawnedProcess` | `undefined` | Función personalizada para generar el proceso de Claude Code. Use para ejecutar Claude Code en máquinas virtuales, contenedores o entornos remotos |

367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (mensaje mínimo) | Configuración de mensaje del sistema. Pase una cadena para un mensaje personalizado, o `{ type: 'preset', preset: 'claude_code' }` para usar el mensaje del sistema de Claude Code. Cuando use la forma de objeto preestablecido, agregue `append` para extenderlo con instrucciones adicionales, y establezca `excludeDynamicSections: true` para mover el contexto por sesión al primer mensaje de usuario para [mejor reutilización de caché de mensaje en máquinas](/es/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |367| `systemPrompt` | `string \| { type: 'preset'; preset: 'claude_code'; append?: string; excludeDynamicSections?: boolean }` | `undefined` (mensaje mínimo) | Configuración de mensaje del sistema. Pase una cadena para un mensaje personalizado, o `{ type: 'preset', preset: 'claude_code' }` para usar el mensaje del sistema de Claude Code. Cuando use la forma de objeto preestablecido, agregue `append` para extenderlo con instrucciones adicionales, y establezca `excludeDynamicSections: true` para mover el contexto por sesión al primer mensaje de usuario para [mejor reutilización de caché de mensaje en máquinas](/es/agent-sdk/modifying-system-prompts#improve-prompt-caching-across-users-and-machines) |

368| `thinking` | [`ThinkingConfig`](#thinking-config) | `{ type: 'adaptive' }` para modelos compatibles | Controla el comportamiento de pensamiento/razonamiento de Claude. Vea [`ThinkingConfig`](#thinking-config) para opciones |368| `thinking` | [`ThinkingConfig`](#thinkingconfig) | `{ type: 'adaptive' }` para modelos compatibles | Controla el comportamiento de pensamiento/razonamiento de Claude. Vea [`ThinkingConfig`](#thinkingconfig) para opciones |

370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuración de herramientas. Pase una matriz de nombres de herramientas o use el preestablecido para obtener las herramientas predeterminadas de Claude Code |370| `tools` | `string[] \| { type: 'preset'; preset: 'claude_code' }` | `undefined` | Configuración de herramientas. Pase una matriz de nombres de herramientas o use el preestablecido para obtener las herramientas predeterminadas de Claude Code |

371 371

372### Objeto `Query`372### Objeto `Query`

410| `initializationResult()` | Devuelve el resultado de inicialización completo incluyendo comandos compatibles, modelos, información de cuenta y configuración de estilo de salida |410| `initializationResult()` | Devuelve el resultado de inicialización completo incluyendo comandos compatibles, modelos, información de cuenta y configuración de estilo de salida |

493| `background` | No | Ejecute este agente como una tarea de fondo no bloqueante cuando se invoque |493| `background` | No | Ejecute este agente como una tarea de fondo no bloqueante cuando se invoque |

494| `memory` | No | Fuente de memoria para este agente: `'user'`, `'project'`, o `'local'` |494| `memory` | No | Fuente de memoria para este agente: `'user'`, `'project'`, o `'local'` |

495| `effort` | No | Nivel de esfuerzo de razonamiento para este agente. Acepta un nivel nombrado o un entero |495| `effort` | No | Nivel de esfuerzo de razonamiento para este agente. Acepta un nivel nombrado o un entero |

496| `permissionMode` | No | Modo de permiso para la ejecución de herramientas dentro de este agente. Vea [`PermissionMode`](#permission-mode) |496| `permissionMode` | No | Modo de permiso para la ejecución de herramientas dentro de este agente. Vea [`PermissionMode`](#permissionmode) |

497| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Recordatorio crítico agregado al mensaje del sistema |497| `criticalSystemReminder_EXPERIMENTAL` | No | Experimental: Recordatorio crítico agregado al mensaje del sistema |

498 498

499### `AgentMcpServerSpec`499### `AgentMcpServerSpec`

626 | "default" // Comportamiento de permiso estándar626 | "default" // Comportamiento de permiso estándar

627 | "acceptEdits" // Auto-aceptar ediciones de archivo627 | "acceptEdits" // Auto-aceptar ediciones de archivo

628 | "bypassPermissions" // Omitir todas las verificaciones de permiso628 | "bypassPermissions" // Omitir todas las verificaciones de permiso

629 | "plan" // Modo de planificación - sin ejecución629 | "plan" // Modo de planificación - solo herramientas de lectura

630 | "dontAsk" // No solicitar permisos, negar si no está preaprobado630 | "dontAsk" // No solicitar permisos, negar si no está preaprobado

631 | "auto"; // Usar un clasificador de modelo para aprobar o negar cada llamada de herramienta631 | "auto"; // Usar un clasificador de modelo para aprobar o negar cada llamada de herramienta

632```632```

651```651```

652 652

654| :--------------- | :------------------------------------------- | :---------------------------------------------------------------------------------------------------------- |654| :--------------- | :------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

656| `suggestions` | [`PermissionUpdate`](#permission-update)`[]` | Actualizaciones de permiso sugeridas para que el usuario no sea solicitado nuevamente para esta herramienta |656| `suggestions` | [`PermissionUpdate`](#permissionupdate)`[]` | Actualizaciones de permiso sugeridas para que el usuario no sea solicitado nuevamente para esta herramienta. Los mensajes de Bash incluyen una sugerencia con el destino `localSettings` [destination](#permissionupdatedestination), por lo que devolverlo en `updatedPermissions` escribe la regla en `.claude/settings.local.json` y persiste entre sesiones. |

2379 | McpClaudeAIProxyServerConfig;2379 | McpClaudeAIProxyServerConfig;

2380```2380```

2381 2381

2382Vea [`McpServerConfig`](#mcp-server-config) para detalles sobre cada tipo de transporte.2382Vea [`McpServerConfig`](#mcpserverconfig) para detalles sobre cada tipo de transporte.

2383 2383

2384### `AccountInfo`2384### `AccountInfo`

2385 2385

2825```2825```

2826 2826

2828| :-------------------------- | :------------------------------------------------------ | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |2828| :-------------------------- | :---------------------------------------------------- | :------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

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

2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Mapa de categorías de violación a patrones a ignorar (por ejemplo, `{ file: ['/tmp/*'], network: ['localhost'] }`) |2835| `ignoreViolations` | `Record<string, string[]>` | `undefined` | Mapa de categorías de violación a patrones a ignorar (por ejemplo, `{ file: ['/tmp/*'], network: ['localhost'] }`) |

2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configuración de binario ripgrep personalizado para entornos sandbox |2837| `ripgrep` | `{ command: string; args?: string[] }` | `undefined` | Configuración de binario ripgrep personalizado para entornos sandbox |

data-usage.md +1 −1

Details

67 67

68El diagrama a continuación muestra cómo Claude Code se conecta a servicios externos durante la instalación y operación normal. Las líneas sólidas indican conexiones requeridas, mientras que las líneas punteadas representan flujos de datos opcionales o iniciados por el usuario.68El diagrama a continuación muestra cómo Claude Code se conecta a servicios externos durante la instalación y operación normal. Las líneas sólidas indican conexiones requeridas, mientras que las líneas punteadas representan flujos de datos opcionales o iniciados por el usuario.

69 69

70<img src="https://mintcdn.com/claude-code/YcBW2H7CArGcduPb/images/claude-code-data-flow.svg?fit=max&auto=format&n=YcBW2H7CArGcduPb&q=85&s=b600a89f84fc86f9ff7be00a466c0635" alt="Diagrama que muestra las conexiones externas de Claude Code: instalar/actualizar se conecta al servidor de distribución, y las solicitudes del usuario se conectan a servicios de Anthropic incluyendo autenticación de consola, API pública, y opcionalmente Statsig, Sentry e informes de errores" width="720" height="520" data-path="images/claude-code-data-flow.svg" />70<img src="https://mintcdn.com/claude-code/RcOyXc06Ja8cuvMZ/images/claude-code-data-flow.svg?fit=max&auto=format&n=RcOyXc06Ja8cuvMZ&q=85&s=b5be40abf333defe984993af89546c19" alt="Diagrama que muestra las conexiones externas de Claude Code: instalar/actualizar se conecta al servidor de distribución, y las solicitudes del usuario se conectan a servicios de Anthropic incluyendo autenticación de consola, API pública, y opcionalmente Statsig, Sentry e informes de errores" width="720" height="520" data-path="images/claude-code-data-flow.svg" />

71 71

72Claude Code se ejecuta localmente. Para interactuar con el LLM, Claude Code envía datos a través de la red. Estos datos incluyen todos los indicadores del usuario y salidas del modelo, cifrados en tránsito a través de TLS 1.2+. Claude Code es compatible con la mayoría de VPN y proxies LLM populares.72Claude Code se ejecuta localmente. Para interactuar con el LLM, Claude Code envía datos a través de la red. Estos datos incluyen todos los indicadores del usuario y salidas del modelo, cifrados en tránsito a través de TLS 1.2+. Claude Code es compatible con la mayoría de VPN y proxies LLM populares.

73 73

desktop.md +5 −3

Details

282 282

283### Trabajar en paralelo con sesiones283### Trabajar en paralelo con sesiones

284 284

285Haga clic en **+ New session** en la barra lateral, o presione **Cmd+N** en macOS o **Ctrl+N** en Windows, para trabajar en múltiples tareas en paralelo. Presione **Ctrl+Tab** y **Ctrl+Shift+Tab** para ciclar a través de sesiones en la barra lateral. Para repositorios de Git, cada sesión obtiene su propia copia aislada de su proyecto usando [Git worktrees](/es/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees), por lo que los cambios en una sesión no afectan otras sesiones hasta que los confirme.285Haga clic en **+ New session** en la barra lateral, o presione **Cmd+N** en macOS o **Ctrl+N** en Windows, para trabajar en múltiples tareas en paralelo. Presione **Ctrl+Tab** y **Ctrl+Shift+Tab** para ciclar a través de sesiones en la barra lateral. Para repositorios de Git, cada sesión obtiene su propia copia aislada de su proyecto usando [Git worktrees](/es/worktrees), por lo que los cambios en una sesión no afectan otras sesiones hasta que los confirme.

286

287Para ver dos sesiones a la vez, mantenga presionado **Cmd** en macOS o **Ctrl** en Windows y haga clic en una sesión en la barra lateral. La sesión se abre en un segundo panel junto al que ya tiene abierto. Mientras la división está activa, hacer clic en otra sesión de la barra lateral reemplaza el panel que tenga el foco. Presione **Cmd+\\** en macOS o **Ctrl+\\** en Windows para cerrar el panel enfocado y volver a una única sesión.

286 288

287Los worktrees se almacenan en `<project-root>/.claude/worktrees/` de forma predeterminada. Puede cambiar esto a un directorio personalizado en Configuración → Claude Code bajo "Worktree location". También puede establecer un prefijo de rama que se antepone a cada nombre de rama de worktree, lo que es útil para mantener las ramas creadas por Claude organizadas. Para eliminar un worktree cuando haya terminado, pase el cursor sobre la sesión en la barra lateral y haga clic en el icono de archivo. Para que las sesiones se archiven automáticamente cuando su solicitud de extracción se fusiona o cierra, active **Auto-archive after PR merge or close** en Configuración → Claude Code. Auto-archive solo se aplica a sesiones locales que han terminado de ejecutarse.289Los worktrees se almacenan en `<project-root>/.claude/worktrees/` de forma predeterminada. Puede cambiar esto a un directorio personalizado en Configuración → Claude Code bajo "Worktree location". También puede establecer un prefijo de rama que se antepone a cada nombre de rama de worktree, lo que es útil para mantener las ramas creadas por Claude organizadas. Para eliminar un worktree cuando haya terminado, pase el cursor sobre la sesión en la barra lateral y haga clic en el icono de archivo. Para que las sesiones se archiven automáticamente cuando su solicitud de extracción se fusiona o cierra, active **Auto-archive after PR merge or close** en Configuración → Claude Code. Auto-archive solo se aplica a sesiones locales que han terminado de ejecutarse.

288 290

289Para incluir archivos ignorados por git como `.env` en nuevos worktrees, cree un [archivo `.worktreeinclude`](/es/common-workflows#copy-gitignored-files-to-worktrees) en la raíz de su proyecto.291Para incluir archivos ignorados por git como `.env` en nuevos worktrees, cree un [archivo `.worktreeinclude`](/es/worktrees#copy-gitignored-files-into-worktrees) en la raíz de su proyecto.

290 292

291<Note>293<Note>

292 El aislamiento de sesión requiere [Git](https://git-scm.com/downloads). La mayoría de las Macs incluyen Git de forma predeterminada. Ejecute `git --version` en Terminal para verificar. En Windows, Git es necesario para que la pestaña Code funcione: [descargue Git para Windows](https://git-scm.com/downloads/win), instálelo y reinicie la aplicación. Si encuentra errores de Git, pida ayuda a Claude en la [pestaña Cowork](https://claude.com/product/cowork) para solucionar problemas de su configuración.294 El aislamiento de sesión requiere [Git](https://git-scm.com/downloads). La mayoría de las Macs incluyen Git de forma predeterminada. Ejecute `git --version` en Terminal para verificar. En Windows, Git es necesario para que la pestaña Code funcione: [descargue Git para Windows](https://git-scm.com/downloads/win), instálelo y reinicie la aplicación. Si encuentra errores de Git, pida ayuda a Claude en la [pestaña Cowork](https://claude.com/product/cowork) para solucionar problemas de su configuración.

516 518

517Para establecer variables de entorno para sesiones locales y servidores de desarrollo en cualquier plataforma, abra el menú desplegable de entorno en el cuadro de solicitud, pase el cursor sobre **Local** y haga clic en el icono de engranaje para abrir el editor de entorno local. Las variables que guarda aquí se almacenan cifradas en su máquina y se aplican a cada sesión local y servidor de vista previa que inicia. También puede agregar variables a la clave `env` en su archivo `~/.claude/settings.json`, aunque estas llegan solo a sesiones de Claude y no a servidores de desarrollo. Consulte [variables de entorno](/es/env-vars) para la lista completa de variables compatibles.519Para establecer variables de entorno para sesiones locales y servidores de desarrollo en cualquier plataforma, abra el menú desplegable de entorno en el cuadro de solicitud, pase el cursor sobre **Local** y haga clic en el icono de engranaje para abrir el editor de entorno local. Las variables que guarda aquí se almacenan cifradas en su máquina y se aplican a cada sesión local y servidor de vista previa que inicia. También puede agregar variables a la clave `env` en su archivo `~/.claude/settings.json`, aunque estas llegan solo a sesiones de Claude y no a servidores de desarrollo. Consulte [variables de entorno](/es/env-vars) para la lista completa de variables compatibles.

518 520

519[Extended thinking](/es/common-workflows#use-extended-thinking-thinking-mode) está habilitado de forma predeterminada, lo que mejora el rendimiento en tareas de razonamiento complejo pero usa tokens adicionales. Para deshabilitar el pensamiento por completo, establezca `MAX_THINKING_TOKENS` en `0` en el editor de entorno local. En modelos con [razonamiento adaptativo](/es/model-config#adjust-effort-level), cualquier otro valor de `MAX_THINKING_TOKENS` se ignora porque el razonamiento adaptativo controla la profundidad del pensamiento en su lugar. En Opus 4.6 y Sonnet 4.6, establezca `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` en `1` para usar un presupuesto de pensamiento fijo; Opus 4.7 siempre usa razonamiento adaptativo y no tiene modo de presupuesto fijo.521[Extended thinking](/es/model-config#extended-thinking) está habilitado de forma predeterminada, lo que mejora el rendimiento en tareas de razonamiento complejo pero usa tokens adicionales. Para deshabilitar el pensamiento por completo, establezca `MAX_THINKING_TOKENS` en `0` en el editor de entorno local. En modelos con [razonamiento adaptativo](/es/model-config#adjust-effort-level), cualquier otro valor de `MAX_THINKING_TOKENS` se ignora porque el razonamiento adaptativo controla la profundidad del pensamiento en su lugar. En Opus 4.6 y Sonnet 4.6, establezca `CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING` en `1` para usar un presupuesto de pensamiento fijo; Opus 4.7 siempre usa razonamiento adaptativo y no tiene modo de presupuesto fijo.

520 522

521### Sesiones remotas523### Sesiones remotas

522 524

features-overview.md +49 −12

Details

12 Para saber cómo funciona el bucle agentico central, consulte [Cómo funciona Claude Code](/es/how-claude-code-works).12 Para saber cómo funciona el bucle agentico central, consulte [Cómo funciona Claude Code](/es/how-claude-code-works).

13</Note>13</Note>

14 14

~~15**¿Nuevo en Claude Code?** Comience con [CLAUDE.md](/es/memory) para convenciones de proyecto. Agregue otras extensiones según sea necesario.~~15**¿Nuevo en Claude Code?** Comience con [CLAUDE.md](/es/memory) para convenciones de proyecto, luego agregue otras extensiones [según surjan desencadenantes específicos](#build-your-setup-over-time).

16 16

17## Descripción general17## Descripción general

18 18

23* **[MCP](/es/mcp)** conecta Claude a servicios y herramientas externas23* **[MCP](/es/mcp)** conecta Claude a servicios y herramientas externas

24* **[Subagents](/es/sub-agents)** ejecutan sus propios bucles en contexto aislado, devolviendo resúmenes24* **[Subagents](/es/sub-agents)** ejecutan sus propios bucles en contexto aislado, devolviendo resúmenes

25* **[Agent teams](/es/agent-teams)** coordinan múltiples sesiones independientes con tareas compartidas y mensajería punto a punto25* **[Agent teams](/es/agent-teams)** coordinan múltiples sesiones independientes con tareas compartidas y mensajería punto a punto

~~26* **[Hooks](/es/hooks)** se ejecutan fuera del bucle completamente como scripts deterministas~~26* **[Hooks](/es/hooks-guide)** se disparan en eventos del ciclo de vida y pueden ejecutar un script, solicitud HTTP, prompt o subagent

27* **[Plugins](/es/plugins)** y **[marketplaces](/es/plugin-marketplaces)** empaquetan y distribuyen estas características27* **[Plugins](/es/plugins)** y **[marketplaces](/es/plugin-marketplaces)** empaquetan y distribuyen estas características

28 28

29[Skills](/es/skills) son la extensión más flexible. Una skill es un archivo markdown que contiene conocimiento, flujos de trabajo o instrucciones. Puede invocar skills con un comando como `/deploy`, o Claude puede cargarlas automáticamente cuando sea relevante. Las skills pueden ejecutarse en su conversación actual o en un contexto aislado a través de subagents.29[Skills](/es/skills) son la extensión más flexible. Una skill es un archivo markdown que contiene conocimiento, flujos de trabajo o instrucciones. Puede invocar skills con un comando como `/deploy`, o Claude puede cargarlas automáticamente cuando sea relevante. Las skills pueden ejecutarse en su conversación actual o en un contexto aislado a través de subagents.

39| **Subagent** | Contexto de ejecución aislado que devuelve resultados resumidos | Aislamiento de contexto, tareas paralelas, trabajadores especializados | Tarea de investigación que lee muchos archivos pero devuelve solo hallazgos clave |39| **Subagent** | Contexto de ejecución aislado que devuelve resultados resumidos | Aislamiento de contexto, tareas paralelas, trabajadores especializados | Tarea de investigación que lee muchos archivos pero devuelve solo hallazgos clave |

40| **[Agent teams](/es/agent-teams)** | Coordinar múltiples sesiones independientes de Claude Code | Investigación paralela, desarrollo de nuevas características, depuración con hipótesis competidoras | Generar revisores para verificar seguridad, rendimiento y pruebas simultáneamente |40| **[Agent teams](/es/agent-teams)** | Coordinar múltiples sesiones independientes de Claude Code | Investigación paralela, desarrollo de nuevas características, depuración con hipótesis competidoras | Generar revisores para verificar seguridad, rendimiento y pruebas simultáneamente |

41| **MCP** | Conectar a servicios externos | Datos o acciones externas | Consultar su base de datos, publicar en Slack, controlar un navegador |41| **MCP** | Conectar a servicios externos | Datos o acciones externas | Consultar su base de datos, publicar en Slack, controlar un navegador |

43 43

44**[Plugins](/es/plugins)** son la capa de empaquetamiento. Un plugin agrupa skills, hooks, subagents y servidores MCP en una única unidad instalable. Las skills de plugin tienen espacios de nombres (como `/my-plugin:review`) para que múltiples plugins puedan coexistir. Use plugins cuando desee reutilizar la misma configuración en múltiples repositorios o distribuir a otros a través de un **[marketplace](/es/plugin-marketplaces)**.44**[Plugins](/es/plugins)** son la capa de empaquetamiento. Un plugin agrupa skills, hooks, subagents y servidores MCP en una única unidad instalable. Las skills de plugin tienen espacios de nombres (como `/my-plugin:review`) para que múltiples plugins puedan coexistir. Use plugins cuando desee reutilizar la misma configuración en múltiples repositorios o distribuir a otros a través de un **[marketplace](/es/plugin-marketplaces)**.

45 45

46### Construir su configuración con el tiempo

48No necesita configurar todo de antemano. Cada característica tiene un desencadenante reconocible, y la mayoría de los equipos las agregan en aproximadamente este orden:

50| Desencadenante | Agregar |

51| :-------------------------------------------------------------------------------- | :------------------------------------------------------------- |

52| Claude se equivoca en una convención o comando dos veces | Agréguelo a [CLAUDE.md](/es/memory) |

53| Sigue escribiendo el mismo prompt para iniciar una tarea | Guárdelo como una [skill](/es/skills) invocable por el usuario |

54| Pega el mismo manual o procedimiento de varios pasos en el chat por tercera vez | Capturarlo como una [skill](/es/skills) |

55| Sigue copiando datos de una pestaña del navegador que Claude no puede ver | Conecte ese sistema como un [servidor MCP](/es/mcp) |

56| Una tarea secundaria inunda su conversación con salida que no volverá a consultar | Enrutarlo a través de un [subagent](/es/sub-agents) |

57| Desea que algo suceda cada vez sin preguntar | Escriba un [hook](/es/hooks-guide) |

58| Un segundo repositorio necesita la misma configuración | Empaquételo como un [plugin](/es/plugins) |

60Los mismos desencadenantes le dicen cuándo actualizar lo que ya tiene. Un error repetido o un comentario de revisión recurrente es una edición de CLAUDE.md, no una corrección única en el chat. Un flujo de trabajo que sigue ajustando manualmente es una skill que necesita otra revisión.

46### Comparar características similares62### Comparar características similares

47 63

48Algunas características pueden parecer similares. Aquí se explica cómo distinguirlas.64Algunas características pueden parecer similares. Aquí se explica cómo distinguirlas.

55 * **Subagents** son trabajadores aislados que se ejecutan separadamente de su conversación principal71 * **Subagents** son trabajadores aislados que se ejecutan separadamente de su conversación principal

56 72

~~58 | ------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ |~~74 | -------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------ |

77 | **Impacto de [ventana de contexto](/es/context-window)** | Se agrega a su ventana principal | Usa una ventana separada con sus propios tokens de entrada y salida |

62 79

63 **Las skills pueden ser de referencia o acción.** Las skills de referencia proporcionan conocimiento que Claude usa en toda su sesión (como su guía de estilo de API). Las skills de acción le dicen a Claude que haga algo específico (como `/deploy` que ejecuta su flujo de trabajo de implementación).80 **Las skills pueden ser de referencia o acción.** Las skills de referencia proporcionan conocimiento que Claude usa en toda su sesión (como su guía de estilo de API). Las skills de acción le dicen a Claude que haga algo específico (como `/deploy` que ejecuta su flujo de trabajo de implementación).

131 | Aspecto | MCP | Skill |148 | Aspecto | MCP | Skill |

132 | --------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |149 | --------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |

135 | **Ejemplos** | Integración de Slack, consultas de base de datos, control de navegador | Lista de verificación de revisión de código, flujo de trabajo de implementación, guía de estilo de API |152 | **Ejemplos** | Integración de Slack, consultas de base de datos, control de navegador | Lista de verificación de revisión de código, flujo de trabajo de implementación, guía de estilo de API |

136 153

137 Estos resuelven problemas diferentes y funcionan bien juntos:154 Estos resuelven problemas diferentes y funcionan bien juntos:

142 159

143 Ejemplo: Un servidor MCP conecta Claude a su base de datos. Una skill enseña a Claude su modelo de datos, patrones de consulta comunes y qué tablas usar para diferentes tareas.160 Ejemplo: Un servidor MCP conecta Claude a su base de datos. Una skill enseña a Claude su modelo de datos, patrones de consulta comunes y qué tablas usar para diferentes tareas.

144 </Tab>161 </Tab>

162

163 <Tab title="Hook vs Skill">

164 Un hook se dispara en un evento del ciclo de vida; una skill se carga en contexto para que Claude la aplique.

165

166 | Aspecto | Hook | Skill |

167 | --------------------- | -------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |

168 | **Se ejecuta** | Un comando shell, solicitud HTTP, prompt LLM o subagent | Instrucciones que Claude lee y sigue |

169 | **Desencadenado por** | [Eventos del ciclo de vida](/es/hooks#hook-events) como `PostToolUse` o `SessionStart` | Usted escribiendo `/<name>`, o Claude haciendo coincidir la descripción con su tarea |

170 | **Determinismo** | Siempre se dispara en su evento; el desencadenante está garantizado | Claude interpreta las instrucciones; el resultado puede variar |

171 | **Costo de contexto** | Cero a menos que el hook devuelva salida | La descripción se carga cada sesión; el contenido completo se carga cuando se usa |

172 | **Mejor para** | Linting después de ediciones, bloquear comandos inseguros, logging, notificaciones | Flujos de trabajo que necesitan razonamiento, material de referencia, tareas de varios pasos |

173

174 **Use un hook** cuando la acción debe suceder de la misma manera cada vez y no necesita que Claude piense. Por ejemplo: formatear al guardar, rechazar `rm -rf /`, publicar un mensaje de Slack cuando termina una sesión.

175

176 **Use una skill** cuando Claude debe decidir cómo aplicar los pasos, o cuando el contenido es conocimiento en lugar de un script. Por ejemplo: una lista de verificación `/release`, su guía de estilo de API, un manual de depuración.

177

178 **Ponga guardrails en hooks.** Una instrucción como "nunca edite `.env`" en CLAUDE.md o una skill es una solicitud, no una garantía. Un hook `PreToolUse` que bloquea la edición es cumplimiento. Si una regla debe mantenerse cada vez, hágala un hook en lugar de una instrucción de prompt.

179

180 **La salida del hook aterriza en contexto.** Un hook `PostToolUse` que ejecuta su linter alimenta resultados de vuelta como texto que Claude lee; una skill `/fix-lint` le dice a Claude cómo resolverlos.

181 </Tab>

145</Tabs>182</Tabs>

146 183

147### Entender cómo se superponen las características184### Entender cómo se superponen las características

168 205

169## Entender costos de contexto206## Entender costos de contexto

170 207

171Cada característica que agrega consume algo del contexto de Claude. Demasiado puede llenar su ventana de contexto, pero también puede agregar ruido que hace que Claude sea menos efectivo; las skills pueden no desencadenarse correctamente, o Claude puede perder de vista sus convenciones. Entender estos compromisos lo ayuda a construir una configuración efectiva.208Cada característica que agrega consume algo del contexto de Claude. Demasiado puede llenar su ventana de contexto, pero también puede agregar ruido que hace que Claude sea menos efectivo; las skills pueden no desencadenarse correctamente, o Claude puede perder de vista sus convenciones. Entender estos compromisos lo ayuda a construir una configuración efectiva. Para una vista interactiva de cómo estas características se combinan en una sesión en ejecución, consulte [Explorar la ventana de contexto](/es/context-window).

172 209

173### Costo de contexto por característica210### Costo de contexto por característica

174 211

178| ------------------ | -------------------------------- | --------------------------------------------------------- | ----------------------------------------------------- |215| ------------------ | -------------------------------- | --------------------------------------------------------- | ----------------------------------------------------- |

184 221

188 225

189Cada característica se carga en diferentes puntos de su sesión. Las pestañas a continuación explican cuándo se carga cada una y qué entra en contexto.226Cada característica se carga en diferentes puntos de su sesión. Las pestañas a continuación explican cuándo se carga cada una y qué entra en contexto.

190 227

191<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Carga de contexto: CLAUDE.md y MCP se cargan al inicio de sesión y permanecen en cada solicitud. Las skills cargan descripciones al inicio, contenido completo al invocar. Los subagents obtienen contexto aislado. Los hooks se ejecutan externamente." width="720" height="410" data-path="images/context-loading.svg" />228<img src="https://mintcdn.com/claude-code/6yTCYq1p37ZB8-CQ/images/context-loading.svg?fit=max&auto=format&n=6yTCYq1p37ZB8-CQ&q=85&s=5a58ce953a35a2412892015e2ad6cb67" alt="Carga de contexto: CLAUDE.md se carga al inicio de sesión y permanece en cada solicitud. Los nombres de herramientas MCP se cargan al inicio con esquemas completos diferidos hasta el uso. Las skills cargan descripciones al inicio, contenido completo al invocar. Los subagents obtienen contexto aislado. Los hooks se ejecutan externamente." width="720" height="410" data-path="images/context-loading.svg" />

192 229

193<Tabs>230<Tabs>

194 <Tab title="CLAUDE.md">231 <Tab title="CLAUDE.md">

202 </Tab>239 </Tab>

203 240

204 <Tab title="Skills">241 <Tab title="Skills">

205 Las skills son capacidades adicionales en el kit de herramientas de Claude. Pueden ser material de referencia (como una guía de estilo de API) o flujos de trabajo invocables que desencadena con `/<name>` (como `/deploy`). Claude Code se envía con [skills incluidas](/es/skills#bundled-skills) como `/simplify`, `/batch` y `/debug` que funcionan de inmediato. También puede crear las suyas propias. Claude usa skills cuando es apropiado, o puede invocar una directamente.242 Las skills son capacidades adicionales en el kit de herramientas de Claude. Pueden ser material de referencia (como una guía de estilo de API) o flujos de trabajo invocables que desencadena con `/<name>` (como `/deploy`). Claude Code incluye [skills incluidas](/es/commands) como `/simplify`, `/batch` y `/debug` que funcionan de inmediato. También puede crear las suyas propias. Claude usa skills cuando es apropiado, o puede invocar una directamente.

206 243

207 **Cuándo:** Depende de la configuración de la skill. Por defecto, las descripciones se cargan al inicio de sesión y el contenido completo se carga cuando se usa. Para skills solo de usuario (`disable-model-invocation: true`), nada se carga hasta que las invoque.244 **Cuándo:** Depende de la configuración de la skill. Por defecto, las descripciones se cargan al inicio de sesión y el contenido completo se carga cuando se usa. Para skills solo de usuario (`disable-model-invocation: true`), nada se carga hasta que las invoque.

208 245

220 <Tab title="Servidores MCP">257 <Tab title="Servidores MCP">

221 **Cuándo:** Inicio de sesión.258 **Cuándo:** Inicio de sesión.

222 259

223 **Qué se carga:** Todas las definiciones de herramientas y esquemas JSON de servidores conectados.260 **Qué se carga:** Nombres de herramientas de servidores conectados. Los esquemas JSON completos permanecen diferidos hasta que Claude necesita una herramienta específica.

224 261

225 **Costo de contexto:** [Búsqueda de herramientas](/es/mcp#scale-with-mcp-tool-search) (habilitada por defecto) carga herramientas MCP hasta el 10% del contexto y difiere el resto hasta que sea necesario.262 **Costo de contexto:** [Búsqueda de herramientas](/es/mcp#scale-with-mcp-tool-search) está habilitada por defecto, por lo que las herramientas MCP inactivas consumen contexto mínimo.

226 263

227 **Nota de confiabilidad:** Las conexiones MCP pueden fallar silenciosamente a mitad de sesión. Si un servidor se desconecta, sus herramientas desaparecen sin advertencia. Claude puede intentar usar una herramienta que ya no existe. Si nota que Claude no puede usar una herramienta MCP a la que podía acceder anteriormente, verifique la conexión con `/mcp`.264 **Nota de confiabilidad:** Las conexiones MCP pueden fallar silenciosamente a mitad de sesión. Si un servidor se desconecta, sus herramientas desaparecen sin advertencia. Claude puede intentar usar una herramienta que ya no existe. Si nota que Claude no puede usar una herramienta MCP a la que podía acceder anteriormente, verifique la conexión con `/mcp`.

228 265

247 <Tab title="Hooks">284 <Tab title="Hooks">

248 **Cuándo:** Al desencadenar. Los hooks se disparan en eventos de ciclo de vida específicos como ejecución de herramientas, límites de sesión, envío de prompt, solicitudes de permiso y compactación. Consulte [Hooks](/es/hooks) para la lista completa.285 **Cuándo:** Al desencadenar. Los hooks se disparan en eventos de ciclo de vida específicos como ejecución de herramientas, límites de sesión, envío de prompt, solicitudes de permiso y compactación. Consulte [Hooks](/es/hooks) para la lista completa.

249 286

250 **Qué se carga:** Nada por defecto. Los hooks se ejecutan como scripts externos.287 **Qué se carga:** Nada por defecto. Los hooks se ejecutan fuera de la conversación principal.

251 288

252 **Costo de contexto:** Cero, a menos que el hook devuelva salida que se agregue como mensajes a su conversación.289 **Costo de contexto:** Cero, a menos que el hook devuelva salida que se agregue como mensajes a su conversación.

253 290

hooks.md +5 −5

Details

970Para bloquear un prompt, devuelva un objeto JSON con `decision` establecido en `"block"`:970Para bloquear un prompt, devuelva un objeto JSON con `decision` establecido en `"block"`:

971 971

972| Campo | Descripción |972| Campo | Descripción |

973| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------------------- |973| :------------------ | :---------------------------------------------------------------------------------------------------------------------------------- |

974| `decision` | `"block"` evita que el prompt se procese y lo borra del contexto. Omita para permitir que el prompt continúe |974| `decision` | `"block"` evita que el prompt se procese y lo borra del contexto. Omita para permitir que el prompt continúe |

976| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt enviado. Consulte [Agregar contexto para Claude](#add-context-for-claude) |976| `additionalContext` | Cadena agregada al contexto de Claude junto con el prompt enviado. Consulte [Agregar contexto para Claude](#add-context-for-claude) |

977| `sessionTitle` | Establece el título de la sesión, el mismo efecto que `/rename`. Use para nombrar sesiones automáticamente basándose en el contenido del prompt |977| `sessionTitle` | Establece el título de la sesión. Use para nombrar sesiones automáticamente basándose en el contenido del prompt |

978 978

979```json theme={null}979```json theme={null}

980{980{

2407```2407```

2408 2408

2409| Campo | Descripción |2409| Campo | Descripción |

2410| :------- | :------------------------------------------------------------ |2410| :------- | :------------------------------------------------------------------------------------------------- |

2411| `ok` | `true` permite la acción, `false` la bloquea |2411| `ok` | `true` permite la acción, `false` la bloquea. Consulte el comportamiento por evento a continuación |

2413 2413

2414Lo que sucede en `ok: false` depende del evento:2414Lo que sucede en `ok: false` depende del evento:

2415 2415

permissions.md +5 −120

Details

36| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |36| :------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

38| `acceptEdits` | Acepta automáticamente ediciones de archivos y comandos comunes del sistema de archivos (`mkdir`, `touch`, `mv`, `cp`, etc.) para rutas en el directorio de trabajo o `additionalDirectories` |38| `acceptEdits` | Acepta automáticamente ediciones de archivos y comandos comunes del sistema de archivos (`mkdir`, `touch`, `mv`, `cp`, etc.) para rutas en el directorio de trabajo o `additionalDirectories` |

40| `auto` | Auto-aprueba llamadas de herramientas con comprobaciones de seguridad en segundo plano que verifican que las acciones se alineen con su solicitud. Actualmente una vista previa de investigación |40| `auto` | Auto-aprueba llamadas de herramientas con comprobaciones de seguridad en segundo plano que verifican que las acciones se alineen con su solicitud. Actualmente una vista previa de investigación |

41| `dontAsk` | Deniega automáticamente las herramientas a menos que estén preaprobadas a través de `/permissions` o reglas `permissions.allow` |41| `dontAsk` | Deniega automáticamente las herramientas a menos que estén preaprobadas a través de `/permissions` o reglas `permissions.allow` |

42| `bypassPermissions` | Omite todos los avisos de permisos. Las eliminaciones de directorio raíz y directorio de inicio como `rm -rf /` aún solicitan como un disyuntor de circuito |42| `bypassPermissions` | Omite todos los avisos de permisos. Las eliminaciones de directorio raíz y directorio de inicio como `rm -rf /` aún solicitan como un disyuntor de circuito |

296 296

297* Las reglas de negación de permisos bloquean que Claude intente acceder a recursos restringidos297* Las reglas de negación de permisos bloquean que Claude intente acceder a recursos restringidos

298* Las restricciones de sandbox previenen que comandos Bash alcancen recursos fuera de límites definidos, incluso si una inyección de solicitud omite la toma de decisiones de Claude298* Las restricciones de sandbox previenen que comandos Bash alcancen recursos fuera de límites definidos, incluso si una inyección de solicitud omite la toma de decisiones de Claude

299* Las restricciones del sistema de archivos en el sandbox usan reglas de negación Read y Edit, no configuración de sandbox separada299* Las restricciones del sistema de archivos en el sandbox combinan la configuración [`sandbox.filesystem`](/es/sandboxing) con reglas de negación Read y Edit; ambas se fusionan en el límite final del sandbox

300* Las restricciones de red combinan reglas de permisos WebFetch con las listas `allowedDomains` y `deniedDomains` del sandbox300* Las restricciones de red combinan reglas de permisos WebFetch con las listas `allowedDomains` y `deniedDomains` del sandbox

301 301

302Cuando el sandboxing está habilitado con `autoAllowBashIfSandboxed: true`, que es el valor predeterminado, los comandos Bash en sandbox se ejecutan sin solicitar incluso si sus permisos incluyen `ask: Bash(*)`. El límite del sandbox sustituye el aviso por comando. Las reglas de negación explícitas aún se aplican, y los comandos `rm` o `rmdir` que apunten a `/`, su directorio de inicio u otras rutas críticas del sistema aún desencadenan un aviso. Consulte [modos de sandbox](/es/sandboxing#sandbox-modes) para cambiar este comportamiento.302Cuando el sandboxing está habilitado con `autoAllowBashIfSandboxed: true`, que es el valor predeterminado, los comandos Bash en sandbox se ejecutan sin solicitar incluso si sus permisos incluyen `ask: Bash(*)`. El límite del sandbox sustituye el aviso por comando. Las reglas de negación explícitas aún se aplican, y los comandos `rm` o `rmdir` que apunten a `/`, su directorio de inicio u otras rutas críticas del sistema aún desencadenan un aviso. Consulte [modos de sandbox](/es/sandboxing#sandbox-modes) para cambiar este comportamiento.

316| `allowManagedMcpServersOnly` | Cuando es `true`, solo se respetan `allowedMcpServers` de configuración administrada. `deniedMcpServers` aún se fusiona de todas las fuentes. Consulte [Configuración MCP administrada](/es/mcp#managed-mcp-configuration) |316| `allowManagedMcpServersOnly` | Cuando es `true`, solo se respetan `allowedMcpServers` de configuración administrada. `deniedMcpServers` aún se fusiona de todas las fuentes. Consulte [Configuración MCP administrada](/es/mcp#managed-mcp-configuration) |

317| `allowManagedPermissionRulesOnly` | Cuando es `true`, evita que la configuración de usuario y proyecto defina reglas de permisos `allow`, `ask` o `deny`. Solo se aplican las reglas en configuración administrada |317| `allowManagedPermissionRulesOnly` | Cuando es `true`, evita que la configuración de usuario y proyecto defina reglas de permisos `allow`, `ask` o `deny`. Solo se aplican las reglas en configuración administrada |

318| `blockedMarketplaces` | Lista de bloqueo de fuentes de marketplace. Las fuentes bloqueadas se verifican antes de descargar, por lo que nunca tocan el sistema de archivos. Consulte [restricciones de marketplace administradas](/es/plugin-marketplaces#managed-marketplace-restrictions) |318| `blockedMarketplaces` | Lista de bloqueo de fuentes de marketplace. Las fuentes bloqueadas se verifican antes de descargar, por lo que nunca tocan el sistema de archivos. Consulte [restricciones de marketplace administradas](/es/plugin-marketplaces#managed-marketplace-restrictions) |

319| `channelsEnabled` | Permitir [channels](/es/channels) para usuarios de Team y Enterprise. Sin establecer o `false` bloquea la entrega de mensajes de canal independientemente de lo que los usuarios pasen a `--channels` |319| `channelsEnabled` | Permitir [channels](/es/channels) para la organización. Consulte [controles empresariales](/es/channels#enterprise-controls) para el valor predeterminado en cada plan |

320| `forceRemoteSettingsRefresh` | Cuando es `true`, bloquea el inicio de CLI hasta que la configuración administrada remota se obtenga recientemente y sale si la obtención falla. Consulte [aplicación de cierre de falla](/es/server-managed-settings#enforce-fail-closed-startup) |320| `forceRemoteSettingsRefresh` | Cuando es `true`, bloquea el inicio de CLI hasta que la configuración administrada remota se obtenga recientemente y sale si la obtención falla. Consulte [aplicación de cierre de falla](/es/server-managed-settings#enforce-fail-closed-startup) |

321| `pluginTrustMessage` | Mensaje personalizado agregado a la advertencia de confianza de plugin mostrada antes de la instalación |321| `pluginTrustMessage` | Mensaje personalizado agregado a la advertencia de confianza de plugin mostrada antes de la instalación |

322| `sandbox.filesystem.allowManagedReadPathsOnly` | Cuando es `true`, solo se respetan rutas `filesystem.allowRead` de configuración administrada. `denyRead` aún se fusiona de todas las fuentes |322| `sandbox.filesystem.allowManagedReadPathsOnly` | Cuando es `true`, solo se respetan rutas `filesystem.allowRead` de configuración administrada. `denyRead` aún se fusiona de todas las fuentes |

327`disableBypassPermissionsMode` generalmente se coloca en configuración administrada para aplicar la política organizacional, pero funciona desde cualquier alcance. Un usuario puede establecerlo en su propia configuración para bloquearse a sí mismo del modo de bypass.327`disableBypassPermissionsMode` generalmente se coloca en configuración administrada para aplicar la política organizacional, pero funciona desde cualquier alcance. Un usuario puede establecerlo en su propia configuración para bloquearse a sí mismo del modo de bypass.

328 328

329<Note>329<Note>

330 El acceso a [Remote Control](/es/remote-control) y [sesiones web](/es/claude-code-on-the-web) no se controla mediante una clave de configuración administrada. En planes Team y Enterprise, un administrador habilita o deshabilita estas características en [configuración de administrador de Claude Code](https://claude.ai/admin-settings/claude-code).330 En planes Team y Enterprise, un administrador habilita o deshabilita [Remote Control](/es/remote-control) y [sesiones web](/es/claude-code-on-the-web) en toda la organización en [configuración de administrador de Claude Code](https://claude.ai/admin-settings/claude-code). Remote Control puede deshabilitarse adicionalmente por dispositivo con la configuración administrada [`disableRemoteControl`](/es/settings#available-settings). Las sesiones web no tienen clave de configuración administrada por dispositivo.

331</Note>331</Note>

332 332

333## Revisar denegaciones del modo auto333## Configuración de precedencia

~~334~~

335Cuando el [modo auto](/es/permission-modes#eliminate-prompts-with-auto-mode) deniega una llamada de herramienta, aparece una notificación y la acción denegada se registra en `/permissions` bajo la pestaña Recently denied. Presione `r` en una acción denegada para marcarla para reintentar: cuando salga del diálogo, Claude Code envía un mensaje indicando al modelo que puede reintentar esa llamada de herramienta y reanuda la conversación.

~~336~~

337Para reaccionar a denegaciones programáticamente, use el [hook `PermissionDenied`](/es/hooks#permissiondenied).

~~338~~

339## Configurar el clasificador del modo auto

~~340~~

341El [modo auto](/es/permission-modes#eliminate-prompts-with-auto-mode) utiliza un modelo clasificador para decidir si cada acción es segura de ejecutar sin solicitar. De fábrica, solo confía en el directorio de trabajo y, si está presente, los remotos del repositorio actual. Acciones como empujar a la organización de control de fuente de su empresa o escribir en un bucket de nube de equipo serán bloqueadas como posible exfiltración de datos.

~~342~~

343Para ajustar lo que el clasificador permite o bloquea, agregue instrucciones a su archivo [CLAUDE.md](/es/memory). El clasificador lee CLAUDE.md desde directorios confiables junto a la conversación, por lo que una instrucción como "nunca force push" dirige tanto a Claude como al clasificador al mismo tiempo. Comience aquí para convenciones de proyecto y reglas de comportamiento.

~~344~~

345Para reglas que se aplican en todos los proyectos, como infraestructura confiable o reglas de denegación en toda la organización, use el bloque de configuración `autoMode`. El clasificador lee `autoMode` desde configuración de usuario, `.claude/settings.local.json` y configuración administrada. No lee desde configuración de proyecto compartida en `.claude/settings.json`, porque un repositorio registrado podría inyectar sus propias reglas de permiso.

~~346~~

347| Alcance | Archivo | Usar para |

348| :---------------------------- | :---------------------------- | :---------------------------------------------------------------- |

349| Un desarrollador | `~/.claude/settings.json` | Infraestructura confiable personal |

350| Un proyecto, un desarrollador | `.claude/settings.local.json` | Buckets o servicios confiables por proyecto, gitignored |

351| Organización completa | Configuración administrada | Infraestructura confiable aplicada para todos los desarrolladores |

~~352~~

353Las entradas de cada alcance se combinan. Un desarrollador puede extender `environment`, `allow` y `soft_deny` con entradas personales pero no puede eliminar entradas que proporciona la configuración administrada. Porque las reglas de permiso actúan como excepciones a las reglas de bloqueo dentro del clasificador, una entrada `allow` agregada por desarrollador puede anular una entrada `soft_deny` de organización: la combinación es aditiva, no un límite de política duro. Si necesita una regla que los desarrolladores no puedan eludir, use `permissions.deny` en configuración administrada en su lugar, que bloquea acciones antes de que se consulte el clasificador.

~~354~~

355### Definir infraestructura confiable

~~356~~

357Para la mayoría de las organizaciones, `autoMode.environment` es el único campo que necesita establecer. Le dice al clasificador qué repositorios, buckets y dominios son confiables, sin tocar las reglas de bloqueo y permiso integradas. El clasificador usa `environment` para decidir qué significa "externo": cualquier destino no listado es un objetivo potencial de exfiltración.

~~358~~

359```json theme={null}

360{

361 "autoMode": {

362 "environment": [

363 "Source control: github.example.com/acme-corp and all repos under it",

364 "Trusted cloud buckets: s3://acme-build-artifacts, gs://acme-ml-datasets",

365 "Trusted internal domains: *.corp.example.com, api.internal.example.com",

366 "Key internal services: Jenkins at ci.example.com, Artifactory at artifacts.example.com"

367 ]

368 }

369}

370```

~~371~~

372Las entradas son prosa, no regex o patrones de herramienta. El clasificador las lee como reglas de lenguaje natural. Escríbalas de la manera que describiría su infraestructura a un ingeniero nuevo. Una sección de entorno exhaustiva cubre:

~~373~~

374* **Organización**: el nombre de su empresa y para qué se usa principalmente Claude Code, como desarrollo de software, automatización de infraestructura o ingeniería de datos

375* **Control de fuente**: cada organización de GitHub, GitLab o Bitbucket a la que sus desarrolladores empujan

376* **Proveedores de nube y buckets confiables**: nombres de buckets o prefijos a los que Claude debería poder leer y escribir

377* **Dominios internos confiables**: nombres de host para APIs, paneles y servicios dentro de su red, como `*.internal.example.com`

378* **Servicios internos clave**: CI, registros de artefactos, índices de paquetes internos, herramientas de incidentes

379* **Contexto adicional**: restricciones de industria regulada, infraestructura multiinquilino o requisitos de cumplimiento que afecten lo que el clasificador debería tratar como riesgoso

~~380~~

381Una plantilla de inicio útil: complete los campos entre corchetes y elimine cualquier línea que no se aplique:

~~382~~

383```json theme={null}

384{

385 "autoMode": {

386 "environment": [

387 "Organization: {COMPANY_NAME}. Primary use: {PRIMARY_USE_CASE, e.g. software development, infrastructure automation}",

388 "Source control: {SOURCE_CONTROL, e.g. GitHub org github.example.com/acme-corp}",

389 "Cloud provider(s): {CLOUD_PROVIDERS, e.g. AWS, GCP, Azure}",

390 "Trusted cloud buckets: {TRUSTED_BUCKETS, e.g. s3://acme-builds, gs://acme-datasets}",

391 "Trusted internal domains: {TRUSTED_DOMAINS, e.g. *.internal.example.com, api.example.com}",

392 "Key internal services: {SERVICES, e.g. Jenkins at ci.example.com, Artifactory at artifacts.example.com}",

393 "Additional context: {EXTRA, e.g. regulated industry, multi-tenant infrastructure, compliance requirements}"

394 ]

395 }

396}

397```

~~398~~

399Cuanto más contexto específico proporcione, mejor el clasificador puede distinguir operaciones internas rutinarias de intentos de exfiltración.

~~400~~

401No necesita completar todo a la vez. Un despliegue razonable: comience con los valores predeterminados y agregue su organización de control de fuente y servicios internos clave, que resuelve los falsos positivos más comunes como empujar a sus propios repositorios. Agregue dominios confiables y buckets de nube a continuación. Complete el resto a medida que surjan bloqueos.

~~402~~

403### Anular las reglas de bloqueo y permiso

~~404~~

405Dos campos adicionales le permiten reemplazar las listas de reglas integradas del clasificador: `autoMode.soft_deny` controla qué se bloquea, y `autoMode.allow` controla qué excepciones se aplican. Cada uno es una matriz de descripciones en prosa, leídas como reglas de lenguaje natural.

~~406~~

407Dentro del clasificador, la precedencia es: las reglas `soft_deny` bloquean primero, luego las reglas `allow` anulan como excepciones, luego la intención explícita del usuario anula ambas. Si el mensaje del usuario describe directa y específicamente la acción exacta que Claude está a punto de tomar, el clasificador la permite incluso si una regla `soft_deny` coincide. Las solicitudes generales no cuentan: pedir a Claude que "limpie el repositorio" no autoriza un force-push, pero pedir a Claude que "force-push esta rama" sí.

~~408~~

409Para aflojar: elimine reglas de `soft_deny` cuando los valores predeterminados bloquean algo que su pipeline ya protege con revisión de PR, CI o entornos de ensayo, o agregue a `allow` cuando el clasificador marca repetidamente un patrón rutinario que las excepciones predeterminadas no cubren. Para apretar: agregue a `soft_deny` para riesgos específicos de su entorno que los valores predeterminados pierden, o elimine de `allow` para mantener una excepción predeterminada a las reglas de bloqueo. En todos los casos, ejecute `claude auto-mode defaults` para obtener las listas predeterminadas completas, luego copie y edite: nunca comience desde una lista vacía.

~~410~~

411```json theme={null}

412{

413 "autoMode": {

414 "environment": [

415 "Source control: github.example.com/acme-corp and all repos under it"

416 ],

417 "allow": [

418 "Deploying to the staging namespace is allowed: staging is isolated from production and resets nightly",

419 "Writing to s3://acme-scratch/ is allowed: ephemeral bucket with a 7-day lifecycle policy"

420 ],

421 "soft_deny": [

422 "Never run database migrations outside the migrations CLI, even against dev databases",

423 "Never modify files under infra/terraform/prod/: production infrastructure changes go through the review workflow",

424 "...copy full default soft_deny list here first, then add your rules..."

425 ]

426 }

427}

428```

~~429~~

430<Danger>

431 Establecer `allow` o `soft_deny` reemplaza la lista predeterminada completa para esa sección. Si establece `soft_deny` con una sola entrada, cada regla de bloqueo integrada se descarta: force push, exfiltración de datos, `curl | bash`, despliegues de producción y todas las otras reglas de bloqueo predeterminadas se permiten. Para personalizar de forma segura, ejecute `claude auto-mode defaults` para imprimir las reglas integradas, cópielas en su archivo de configuración, luego revise cada regla contra su propio pipeline y tolerancia de riesgo. Solo elimine reglas para riesgos que su infraestructura ya mitiga.

432</Danger>

~~433~~

434Las tres secciones se evalúan independientemente, por lo que establecer `environment` solo deja intactas las listas predeterminadas `allow` y `soft_deny`.

~~435~~

436### Inspeccionar los valores predeterminados y su configuración efectiva

~~437~~

438Porque establecer `allow` o `soft_deny` reemplaza los valores predeterminados, comience cualquier personalización copiando las listas predeterminadas completas. Tres subcomandos CLI lo ayudan a inspeccionar y validar:

~~439~~

440```bash theme={null}

441claude auto-mode defaults # the built-in environment, allow, and soft_deny rules

442claude auto-mode config # what the classifier actually uses: your settings where set, defaults otherwise

443claude auto-mode critique # get AI feedback on your custom allow and soft_deny rules

444```

~~445~~

446Guarde la salida de `claude auto-mode defaults` en un archivo, edite las listas para que coincidan con su política y pegue el resultado en su archivo de configuración. Después de guardar, ejecute `claude auto-mode config` para confirmar que las reglas efectivas son lo que espera. Si ha escrito reglas personalizadas, `claude auto-mode critique` las revisa y marca entradas que son ambiguas, redundantes o probables de causar falsos positivos.

~~447~~

448## Precedencia de configuración

449 334

450Las reglas de permisos siguen la misma [precedencia de configuración](/es/settings#settings-precedence) que todas las demás configuraciones de Claude Code:335Las reglas de permisos siguen la misma [precedencia de configuración](/es/settings#settings-precedence) que todas las demás configuraciones de Claude Code:

451 336

platforms.md +7 −4

Details

4 4

5# Plataformas e integraciones5# Plataformas e integraciones

6 6

~~7> Elija dónde ejecutar Claude Code y qué conectar. Compare la CLI, Desktop, VS Code, JetBrains, web e integraciones como Chrome, Slack e CI/CD.~~7> Elija dónde ejecutar Claude Code y qué conectar. Compare la CLI, Desktop, VS Code, JetBrains, web, móvil e integraciones como Chrome, Slack e CI/CD.

8 8

9Claude Code ejecuta el mismo motor subyacente en todas partes, pero cada superficie está optimizada para una forma diferente de trabajar. Esta página le ayuda a elegir la plataforma adecuada para su flujo de trabajo y conectar las herramientas que ya utiliza.9Claude Code ejecuta el mismo motor subyacente en todas partes, pero cada superficie está optimizada para una forma diferente de trabajar. Esta página le ayuda a elegir la plataforma adecuada para su flujo de trabajo y conectar las herramientas que ya utiliza.

10 10

13Elija una plataforma según cómo le guste trabajar y dónde viva su proyecto.13Elija una plataforma según cómo le guste trabajar y dónde viva su proyecto.

14 14

16| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |16| :-------------------------------- | :--------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

17| [CLI](/es/quickstart) | Flujos de trabajo de terminal, scripting, servidores remotos | Conjunto completo de características, [Agent SDK](/es/headless), proveedores de terceros |17| [CLI](/es/quickstart) | Flujos de trabajo de terminal, scripting, servidores remotos | Conjunto completo de características, [Agent SDK](/es/headless), [uso de computadora](/es/computer-use) en macOS (Pro y Max), proveedores de terceros |

18| [Desktop](/es/desktop) | Revisión visual, sesiones paralelas, configuración administrada | Visor de diferencias, vista previa de aplicaciones, [uso de computadora](/es/desktop#let-claude-use-your-computer) y [Dispatch](/es/desktop#sessions-from-dispatch) en Pro y Max |18| [Desktop](/es/desktop) | Revisión visual, sesiones paralelas, configuración administrada | Visor de diferencias, vista previa de aplicaciones, [uso de computadora](/es/desktop#let-claude-use-your-computer) y [Dispatch](/es/desktop#sessions-from-dispatch) en Pro y Max |

21| [Web](/es/claude-code-on-the-web) | Tareas de larga duración que no necesitan mucha dirección, o trabajo que debe continuar cuando está desconectado | Nube administrada por Anthropic, continúa después de desconectarse |21| [Web](/es/claude-code-on-the-web) | Tareas de larga duración que no necesitan mucha dirección, o trabajo que debe continuar cuando está desconectado | Nube administrada por Anthropic, continúa después de desconectarse |

22| Móvil | Iniciar y monitorear tareas mientras está lejos de su computadora | Sesiones en la nube desde la aplicación Claude para iOS y Android, [Remote Control](/es/remote-control) para sesiones locales, [Dispatch](/es/desktop#sessions-from-dispatch) a Desktop en Pro y Max |

22 23

23La CLI es la superficie más completa para el trabajo nativo de terminal: scripting, proveedores de terceros y el Agent SDK son solo CLI. Desktop y las extensiones de IDE intercambian algunas características solo de CLI por revisión visual e integración más estrecha del editor. La web se ejecuta en la nube de Anthropic, por lo que las tareas continúan después de desconectarse.24La CLI es la superficie más completa para el trabajo nativo de terminal: scripting y el Agent SDK son solo CLI. Los proveedores de terceros también funcionan en [VS Code](/es/vs-code#use-third-party-providers). Las implementaciones empresariales de [Desktop](/es/desktop) admiten Vertex AI y proveedores de puerta de enlace; para Bedrock o Foundry, use la CLI o VS Code en lugar de Desktop. Desktop y las extensiones de IDE intercambian algunas características solo de CLI por revisión visual e integración más estrecha del editor. La web se ejecuta en la nube de Anthropic, por lo que las tareas continúan después de desconectarse. Móvil es un cliente delgado en esas mismas sesiones en la nube o en una sesión local a través de Remote Control, y puede enviar tareas a Desktop con Dispatch.

24 25

25Puede mezclar superficies en el mismo proyecto. La configuración, la memoria del proyecto y los servidores MCP se comparten entre las superficies locales.26Puede mezclar superficies en el mismo proyecto. La configuración, la memoria del proyecto y los servidores MCP se comparten entre las superficies locales.

26 27

61* [VS Code](/es/vs-code): la extensión Claude Code dentro de su editor62* [VS Code](/es/vs-code): la extensión Claude Code dentro de su editor

62* [JetBrains](/es/jetbrains): la extensión para IntelliJ, PyCharm y otros IDE de JetBrains63* [JetBrains](/es/jetbrains): la extensión para IntelliJ, PyCharm y otros IDE de JetBrains

63* [Claude Code en la web](/es/claude-code-on-the-web): sesiones en la nube que continúan ejecutándose cuando se desconecta64* [Claude Code en la web](/es/claude-code-on-the-web): sesiones en la nube que continúan ejecutándose cuando se desconecta

65* Móvil: la aplicación Claude para [iOS](https://apps.apple.com/us/app/claude-by-anthropic/id6473753684) y [Android](https://play.google.com/store/apps/details?id=com.anthropic.claude) para iniciar y monitorear tareas mientras está lejos de su computadora

64 66

65### Integraciones67### Integraciones

66 68

67* [Chrome](/es/chrome): automatice tareas del navegador con sus sesiones iniciadas69* [Chrome](/es/chrome): automatice tareas del navegador con sus sesiones iniciadas

70* [Uso de computadora](/es/computer-use): permita que Claude abra aplicaciones y controle su pantalla en macOS

68* [GitHub Actions](/es/github-actions): ejecute Claude en su canalización de CI71* [GitHub Actions](/es/github-actions): ejecute Claude en su canalización de CI

69* [GitLab CI/CD](/es/gitlab-ci-cd): lo mismo para GitLab72* [GitLab CI/CD](/es/gitlab-ci-cd): lo mismo para GitLab

70* [Code Review](/es/code-review): revisión automática en cada solicitud de extracción73* [Code Review](/es/code-review): revisión automática en cada solicitud de extracción

plugin-marketplaces.md +8 −6

Details

23 23

24## Tutorial: crear un marketplace local24## Tutorial: crear un marketplace local

25 25

26Este ejemplo crea un marketplace con un plugin: una skill `/quality-review` para revisiones de código. Creará la estructura de directorios, agregará una skill, creará el manifiesto del plugin y el catálogo del marketplace, luego lo instalará y probará.26Este ejemplo crea un marketplace con un plugin: una skill `quality-review` para revisiones de código. Creará la estructura de directorios, agregará una skill, creará el manifiesto del plugin y el catálogo del marketplace, luego lo instalará y probará.

27 27

28<Steps>28<Steps>

29 <Step title="Crear la estructura de directorios">29 <Step title="Crear la estructura de directorios">

35 </Step>35 </Step>

36 36

37 <Step title="Crear la skill">37 <Step title="Crear la skill">

~~38 Cree un archivo `SKILL.md` que defina qué hace la skill `/quality-review`.~~38 Cree un archivo `SKILL.md` que defina qué hace la skill `quality-review`.

39 39

40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}40 ```markdown my-marketplace/plugins/quality-review-plugin/skills/quality-review/SKILL.md theme={null}

41 ---41 ---

59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}59 ```json my-marketplace/plugins/quality-review-plugin/.claude-plugin/plugin.json theme={null}

60 {60 {

61 "name": "quality-review-plugin",61 "name": "quality-review-plugin",

~~62 "description": "Adds a /quality-review skill for quick code reviews",~~62 "description": "Adds a quality-review skill for quick code reviews",

63 "version": "1.0.0"63 "version": "1.0.0"

64 }64 }

65 ```65 ```

82 {82 {

83 "name": "quality-review-plugin",83 "name": "quality-review-plugin",

84 "source": "./plugins/quality-review-plugin",84 "source": "./plugins/quality-review-plugin",

~~85 "description": "Adds a /quality-review skill for quick code reviews"~~85 "description": "Adds a quality-review skill for quick code reviews"

86 }86 }

87 ]87 ]

88 }88 }

99 </Step>99 </Step>

100 100

101 <Step title="Pruébelo">101 <Step title="Pruébelo">

102 Seleccione algo de código en su editor y ejecute su nueva skill.102 Seleccione algo de código en su editor y ejecute su nueva skill. Las skills del plugin tienen un espacio de nombres con el nombre del plugin.

103 103

104 ```shell theme={null}104 ```shell theme={null}

105 /quality-review105 /quality-review-plugin:quality-review

106 ```106 ```

107 </Step>107 </Step>

108</Steps>108</Steps>

694* Para fuentes `hostPattern`: el host del marketplace se compara contra el patrón regex694* Para fuentes `hostPattern`: el host del marketplace se compara contra el patrón regex

695* Para fuentes `pathPattern`: la ruta del sistema de archivos del marketplace se compara contra el patrón regex695* Para fuentes `pathPattern`: la ruta del sistema de archivos del marketplace se compara contra el patrón regex

696 696

697La coincidencia exacta no normaliza URLs: una barra diagonal final, sufijo `.git` o forma `ssh://` versus `https://` se tratan como valores diferentes. Si el marketplace de su organización se puede clonar por más de una forma de URL, prefiera una entrada `hostPattern` sobre una URL literal para que todas las formas coincidan.

698

697Debido a que `strictKnownMarketplaces` se establece en [configuración administrada](/es/settings#settings-files), los usuarios individuales y las configuraciones del proyecto no pueden anular estas restricciones.699Debido a que `strictKnownMarketplaces` se establece en [configuración administrada](/es/settings#settings-files), los usuarios individuales y las configuraciones del proyecto no pueden anular estas restricciones.

698 700

699Para detalles de configuración completos incluyendo todos los tipos de fuente soportados y comparación con `extraKnownMarketplaces`, consulte la [referencia de strictKnownMarketplaces](/es/settings#strictknownmarketplaces).701Para detalles de configuración completos incluyendo todos los tipos de fuente soportados y comparación con `extraKnownMarketplaces`, consulte la [referencia de strictKnownMarketplaces](/es/settings#strictknownmarketplaces).

plugins-reference.md +7 −3

Details

262**Plugins LSP disponibles:**262**Plugins LSP disponibles:**

263 263

265| :--------------- | :------------------------- | :------------------------------------------------------------------------------------------- |265| :------------------ | :------------------------- | :------------------------------------------------------------------------------------------- |

269 269

270Instale el servidor de lenguaje primero, luego instale el plugin desde el marketplace.270Instale el servidor de lenguaje primero, luego instale el plugin desde el marketplace.

271 271

531 531

532Claude Code proporciona dos variables para hacer referencia a rutas de plugins. Ambas se sustituyen en línea en cualquier lugar donde aparezcan en contenido de skills, contenido de agents, comandos de hooks, comandos de monitores y configuraciones de servidores MCP o LSP. Ambas también se exportan como variables de entorno a procesos de hooks y subprocesos de servidores MCP o LSP.532Claude Code proporciona dos variables para hacer referencia a rutas de plugins. Ambas se sustituyen en línea en cualquier lugar donde aparezcan en contenido de skills, contenido de agents, comandos de hooks, comandos de monitores y configuraciones de servidores MCP o LSP. Ambas también se exportan como variables de entorno a procesos de hooks y subprocesos de servidores MCP o LSP.

533 533

534**`${CLAUDE_PLUGIN_ROOT}`**: la ruta absoluta al directorio de instalación de tu plugin. Úsala para hacer referencia a scripts, binarios y archivos de configuración incluidos con el plugin. Esta ruta cambia cuando se actualiza el plugin, así que los archivos que escribas aquí no sobreviven a una actualización.534**`${CLAUDE_PLUGIN_ROOT}`**: la ruta absoluta al directorio de instalación de tu plugin. Úsala para hacer referencia a scripts, binarios y archivos de configuración incluidos con el plugin. Esta ruta cambia cuando se actualiza el plugin. El directorio de la versión anterior permanece en el disco durante aproximadamente siete días después de una actualización antes de la limpieza, pero trátalo como efímero y no escribas estado aquí.

535

536Cuando un plugin se actualiza a mitad de sesión, los comandos de hooks, monitores, servidores MCP y servidores LSP siguen usando la ruta de la versión anterior. Ejecuta `/reload-plugins` para cambiar hooks, servidores MCP y servidores LSP a la nueva ruta; los monitores requieren un reinicio de sesión.

535 537

536**`${CLAUDE_PLUGIN_DATA}`**: un directorio persistente para el estado del plugin que sobrevive a las actualizaciones. Úsalo para dependencias instaladas como `node_modules` o entornos virtuales de Python, código generado, cachés y cualquier otro archivo que deba persistir entre versiones del plugin. El directorio se crea automáticamente la primera vez que se hace referencia a esta variable.538**`${CLAUDE_PLUGIN_DATA}`**: un directorio persistente para el estado del plugin que sobrevive a las actualizaciones. Úsalo para dependencias instaladas como `node_modules` o entornos virtuales de Python, código generado, cachés y cualquier otro archivo que deba persistir entre versiones del plugin. El directorio se crea automáticamente la primera vez que se hace referencia a esta variable.

537 539

677 El directorio `.claude-plugin/` contiene el archivo `plugin.json`. Todos los otros directorios (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) deben estar en la raíz del plugin, no dentro de `.claude-plugin/`.679 El directorio `.claude-plugin/` contiene el archivo `plugin.json`. Todos los otros directorios (commands/, agents/, skills/, output-styles/, themes/, monitors/, hooks/) deben estar en la raíz del plugin, no dentro de `.claude-plugin/`.

678</Warning>680</Warning>

679 681

682Un archivo `CLAUDE.md` en la raíz del plugin no se carga como contexto del proyecto. Los plugins contribuyen contexto a través de skills, agents y hooks en lugar de CLAUDE.md. Para enviar instrucciones que se carguen en el contexto de Claude, colóquelas en un [skill](#skills).

683

680### Referencia de ubicaciones de archivos684### Referencia de ubicaciones de archivos

681 685

security.md +1 −1

Details

27* **Herramienta bash en sandbox**: [Sandbox](/es/sandboxing) comandos bash con aislamiento del sistema de archivos y red, reduciendo solicitudes de permiso mientras se mantiene la seguridad. Habilite con `/sandbox` para definir límites donde Claude Code puede trabajar de forma autónoma27* **Herramienta bash en sandbox**: [Sandbox](/es/sandboxing) comandos bash con aislamiento del sistema de archivos y red, reduciendo solicitudes de permiso mientras se mantiene la seguridad. Habilite con `/sandbox` para definir límites donde Claude Code puede trabajar de forma autónoma

28* **Restricción de acceso de escritura**: Claude Code solo puede escribir en la carpeta donde se inició y sus subcarpetas—no puede modificar archivos en directorios principales sin permiso explícito. Aunque Claude Code puede leer archivos fuera del directorio de trabajo (útil para acceder a bibliotecas del sistema y dependencias), las operaciones de escritura están estrictamente limitadas al alcance del proyecto, creando un límite de seguridad claro28* **Restricción de acceso de escritura**: Claude Code solo puede escribir en la carpeta donde se inició y sus subcarpetas—no puede modificar archivos en directorios principales sin permiso explícito. Aunque Claude Code puede leer archivos fuera del directorio de trabajo (útil para acceder a bibliotecas del sistema y dependencias), las operaciones de escritura están estrictamente limitadas al alcance del proyecto, creando un límite de seguridad claro

29* **Mitigación de fatiga de solicitudes**: Soporte para listas de permitidos de comandos seguros frecuentemente utilizados por usuario, por base de código u por organización29* **Mitigación de fatiga de solicitudes**: Soporte para listas de permitidos de comandos seguros frecuentemente utilizados por usuario, por base de código u por organización

~~30* **Modo Aceptar Ediciones**: Aceptar por lotes múltiples ediciones mientras se mantienen solicitudes de permiso para comandos con efectos secundarios~~30* **Modo Aceptar Ediciones**: Aprueba automáticamente ediciones de archivos y un conjunto fijo de comandos Bash del sistema de archivos como `mkdir`, `touch`, `rm`, `mv`, `cp`, y `sed` para rutas en el directorio de trabajo. Otros comandos Bash y rutas fuera del alcance aún solicitan aprobación

31 31

32### Responsabilidad del usuario32### Responsabilidad del usuario

33 33

settings.md +26 −3

Details

73 73

74En Windows, las rutas mostradas como `~/.claude` se resuelven en `%USERPROFILE%\.claude`.

74***76***

75 77

76## Archivos de configuración78## Archivos de configuración

166| `apiKeyHelper` | Script personalizado, a ejecutarse en `/bin/sh`, para generar un valor de autenticación. Este valor se enviará como encabezados `X-Api-Key` y `Authorization: Bearer` para solicitudes de modelo | `/bin/generate_temp_api_key.sh` |168| `apiKeyHelper` | Script personalizado, a ejecutarse en `/bin/sh`, para generar un valor de autenticación. Este valor se enviará como encabezados `X-Api-Key` y `Authorization: Bearer` para solicitudes de modelo | `/bin/generate_temp_api_key.sh` |

167| `attribution` | Personalizar atribución para commits de git y solicitudes de extracción. Consulte [Configuración de atribución](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |169| `attribution` | Personalizar atribución para commits de git y solicitudes de extracción. Consulte [Configuración de atribución](#attribution-settings) | `{"commit": "🤖 Generated with Claude Code", "pr": ""}` |

168| `autoMemoryDirectory` | Directorio personalizado para almacenamiento de [memoria automática](/es/memory#storage-location). Acepta una ruta absoluta o una ruta con prefijo `~/`. Se acepta desde configuraciones de política y usuario, y desde la bandera `--settings`. No se acepta desde configuraciones de proyecto o local, ya que un repositorio clonado podría proporcionar cualquiera de los archivos para redirigir escrituras de memoria a ubicaciones sensibles | `"~/my-memory-dir"` |170| `autoMemoryDirectory` | Directorio personalizado para almacenamiento de [memoria automática](/es/memory#storage-location). Acepta una ruta absoluta o una ruta con prefijo `~/`. Se acepta desde configuraciones de política y usuario, y desde la bandera `--settings`. No se acepta desde configuraciones de proyecto o local, ya que un repositorio clonado podría proporcionar cualquiera de los archivos para redirigir escrituras de memoria a ubicaciones sensibles | `"~/my-memory-dir"` |

171| `autoMemoryEnabled` | Habilitar [memoria automática](/es/memory#enable-or-disable-auto-memory). Cuando es `false`, Claude no lee ni escribe en el directorio de memoria automática. Predeterminado: `true`. También puede alternar esto con `/memory` durante una sesión | `false` |

169| `autoMode` | Personalizar qué bloquea y permite el clasificador de [modo automático](/es/permission-modes#eliminate-prompts-with-auto-mode). Contiene matrices `environment`, `allow` y `soft_deny` de reglas en prosa. Incluya la cadena literal `"$defaults"` en una matriz para heredar las reglas integradas en esa posición. Consulte [Configurar modo automático](/es/auto-mode-config). No se lee desde configuraciones de proyecto compartidas | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |172| `autoMode` | Personalizar qué bloquea y permite el clasificador de [modo automático](/es/permission-modes#eliminate-prompts-with-auto-mode). Contiene matrices `environment`, `allow` y `soft_deny` de reglas en prosa. Incluya la cadena literal `"$defaults"` en una matriz para heredar las reglas integradas en esa posición. Consulte [Configurar modo automático](/es/auto-mode-config). No se lee desde configuraciones de proyecto compartidas | `{"soft_deny": ["$defaults", "Never run terraform apply"]}` |

170| `autoScrollEnabled` | En [renderizado de pantalla completa](/es/fullscreen), seguir la nueva salida hasta el final de la conversación. Predeterminado: `true`. Aparece en `/config` como **Auto-scroll**. Los avisos de permiso aún se desplazan a la vista cuando esto está desactivado | `false` |173| `autoScrollEnabled` | En [renderizado de pantalla completa](/es/fullscreen), seguir la nueva salida hasta el final de la conversación. Predeterminado: `true`. Aparece en `/config` como **Auto-scroll**. Los avisos de permiso aún se desplazan a la vista cuando esto está desactivado | `false` |

171| `autoUpdatesChannel` | Canal de lanzamiento a seguir para actualizaciones. Use `"stable"` para una versión que típicamente tiene aproximadamente una semana de antigüedad y omite versiones con regresiones importantes, o `"latest"` (predeterminado) para el lanzamiento más reciente | `"stable"` |174| `autoUpdatesChannel` | Canal de lanzamiento a seguir para actualizaciones. Use `"stable"` para una versión que típicamente tiene aproximadamente una semana de antigüedad y omite versiones con regresiones importantes, o `"latest"` (predeterminado) para el lanzamiento más reciente | `"stable"` |

174| `awsAuthRefresh` | Script personalizado que modifica el directorio `.aws` (consulte [configuración avanzada de credenciales](/es/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |177| `awsAuthRefresh` | Script personalizado que modifica el directorio `.aws` (consulte [configuración avanzada de credenciales](/es/amazon-bedrock#advanced-credential-configuration)) | `aws sso login --profile myprofile` |

175| `awsCredentialExport` | Script personalizado que genera JSON con credenciales de AWS (consulte [configuración avanzada de credenciales](/es/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |178| `awsCredentialExport` | Script personalizado que genera JSON con credenciales de AWS (consulte [configuración avanzada de credenciales](/es/amazon-bedrock#advanced-credential-configuration)) | `/bin/generate_aws_grant.sh` |

176| `blockedMarketplaces` | (Solo configuraciones administradas) Lista negra de fuentes de marketplace. Aplicada en adición de marketplace y en instalación, actualización, actualización y auto-actualización de plugins, por lo que un marketplace agregado antes de que se estableciera la política no puede usarse para obtener plugins. Las fuentes bloqueadas se verifican antes de descargar, por lo que nunca tocan el sistema de archivos. Consulte [Restricciones de marketplace administradas](/es/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |179| `blockedMarketplaces` | (Solo configuraciones administradas) Lista negra de fuentes de marketplace. Aplicada en adición de marketplace y en instalación, actualización, actualización y auto-actualización de plugins, por lo que un marketplace agregado antes de que se estableciera la política no puede usarse para obtener plugins. Las fuentes bloqueadas se verifican antes de descargar, por lo que nunca tocan el sistema de archivos. Consulte [Restricciones de marketplace administradas](/es/plugin-marketplaces#managed-marketplace-restrictions) | `[{ "source": "github", "repo": "untrusted/plugins" }]` |

177| `channelsEnabled` | (Solo configuraciones administradas) Permitir [canales](/es/channels) para usuarios de Team y Enterprise. Sin definir o `false` bloquea la entrega de mensajes de canal independientemente de lo que los usuarios pasen a `--channels` | `true` |180| `channelsEnabled` | (Solo configuraciones administradas) Permitir [canales](/es/channels) para la organización. En planes de Claude.ai Team y Enterprise, los canales se bloquean cuando esto no está definido o es `false`. Para cuentas de [Anthropic Console](/es/authentication#claude-console-authentication) que usan autenticación de clave API, los canales se permiten de forma predeterminada a menos que su organización implemente configuraciones administradas, en cuyo caso esta clave debe establecerse en `true` | `true` |

178| `cleanupPeriodDays` | Las sesiones inactivas durante más tiempo que este período se eliminan al inicio (predeterminado: 30 días, mínimo 1). Establecer en `0` se rechaza con un error de validación. También controla el corte de edad para la eliminación automática de [worktrees de subagent huérfanos](/es/worktrees#clean-up-worktrees) al inicio. Para deshabilitar completamente las escrituras de transcripción, establezca la variable de entorno [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/es/env-vars), o en modo no interactivo (`-p`) use la bandera `--no-session-persistence` o la opción SDK `persistSession: false`. | `20` |181| `cleanupPeriodDays` | Las sesiones inactivas durante más tiempo que este período se eliminan al inicio (predeterminado: 30 días, mínimo 1). Establecer en `0` se rechaza con un error de validación. También controla el corte de edad para la eliminación automática de [worktrees de subagent huérfanos](/es/worktrees#clean-up-worktrees) al inicio. Para deshabilitar completamente las escrituras de transcripción, establezca la variable de entorno [`CLAUDE_CODE_SKIP_PROMPT_HISTORY`](/es/env-vars), o en modo no interactivo (`-p`) use la bandera `--no-session-persistence` o la opción SDK `persistSession: false`. | `20` |

179| `companyAnnouncements` | Anuncio a mostrar a los usuarios al inicio. Si se proporcionan múltiples anuncios, se alternarán aleatoriamente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |182| `companyAnnouncements` | Anuncio a mostrar a los usuarios al inicio. Si se proporcionan múltiples anuncios, se alternarán aleatoriamente. | `["Welcome to Acme Corp! Review our code guidelines at docs.acme.com"]` |

180| `defaultShell` | Shell predeterminado para comandos `!` de cuadro de entrada. Acepta `"bash"` (predeterminado) o `"powershell"`. Establecer `"powershell"` enruta comandos `!` interactivos a través de PowerShell en Windows. Requiere `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Consulte [herramienta PowerShell](/es/tools-reference#powershell-tool) | `"powershell"` |183| `defaultShell` | Shell predeterminado para comandos `!` de cuadro de entrada. Acepta `"bash"` (predeterminado) o `"powershell"`. Establecer `"powershell"` enruta comandos `!` interactivos a través de PowerShell en Windows. Requiere `CLAUDE_CODE_USE_POWERSHELL_TOOL=1`. Consulte [herramienta PowerShell](/es/tools-reference#powershell-tool) | `"powershell"` |

183| `disableAutoMode` | Establecer en `"disable"` para evitar que se active el [modo automático](/es/permission-modes#eliminate-prompts-with-auto-mode). Elimina `auto` del ciclo `Shift+Tab` y rechaza `--permission-mode auto` al inicio. Más útil en [configuraciones administradas](/es/permissions#managed-settings) donde los usuarios no pueden anularlo | `"disable"` |186| `disableAutoMode` | Establecer en `"disable"` para evitar que se active el [modo automático](/es/permission-modes#eliminate-prompts-with-auto-mode). Elimina `auto` del ciclo `Shift+Tab` y rechaza `--permission-mode auto` al inicio. Más útil en [configuraciones administradas](/es/permissions#managed-settings) donde los usuarios no pueden anularlo | `"disable"` |

184| `disableDeepLinkRegistration` | Establecer en `"disable"` para evitar que Claude Code registre el controlador de protocolo `claude-cli://` con el sistema operativo al inicio. Los [enlaces profundos](/es/deep-links) permiten que herramientas externas abran una sesión de Claude Code con un indicador rellenado previamente. Útil en entornos donde el registro del controlador de protocolo está restringido o se gestiona por separado | `"disable"` |187| `disableDeepLinkRegistration` | Establecer en `"disable"` para evitar que Claude Code registre el controlador de protocolo `claude-cli://` con el sistema operativo al inicio. Los [enlaces profundos](/es/deep-links) permiten que herramientas externas abran una sesión de Claude Code con un indicador rellenado previamente. Útil en entornos donde el registro del controlador de protocolo está restringido o se gestiona por separado | `"disable"` |

189| `disableRemoteControl` | {/* min-version: 2.1.128 */}Deshabilitar [Control Remoto](/es/remote-control): bloquea `claude remote-control`, la bandera `--remote-control`, auto-inicio y el toggle en sesión. Típicamente colocado en [configuraciones administradas](/es/permissions#managed-settings) para aplicación de MDM por dispositivo, pero funciona desde cualquier ámbito. Requiere Claude Code v2.1.128 o posterior | `true` |

186| `disableSkillShellExecution` | Deshabilitar la ejecución de shell en línea para bloques `` !`...` `` y ` ```! ` en [skills](/es/skills) y comandos personalizados de fuentes de usuario, proyecto, plugin o directorio adicional. Los comandos se reemplazan con `[shell command execution disabled by policy]` en lugar de ejecutarse. Los skills agrupados y administrados no se ven afectados. Más útil en [configuraciones administradas](/es/permissions#managed-settings) donde los usuarios no pueden anularlo | `true` |190| `disableSkillShellExecution` | Deshabilitar la ejecución de shell en línea para bloques `` !`...` `` y ` ```! ` en [skills](/es/skills) y comandos personalizados de fuentes de usuario, proyecto, plugin o directorio adicional. Los comandos se reemplazan con `[shell command execution disabled by policy]` en lugar de ejecutarse. Los skills agrupados y administrados no se ven afectados. Más útil en [configuraciones administradas](/es/permissions#managed-settings) donde los usuarios no pueden anularlo | `true` |

187| `editorMode` | Modo de atajos de teclado para el indicador de entrada: `"normal"` o `"vim"`. Predeterminado: `"normal"`. Aparece en `/config` como **Editor mode** | `"vim"` |191| `editorMode` | Modo de atajos de teclado para el indicador de entrada: `"normal"` o `"vim"`. Predeterminado: `"normal"`. Aparece en `/config` como **Editor mode** | `"vim"` |

188| `effortLevel` | Persistir el [nivel de esfuerzo](/es/model-config#adjust-effort-level) entre sesiones. Acepta `"low"`, `"medium"`, `"high"`, o `"xhigh"`. Se escribe automáticamente cuando ejecuta `/effort` con uno de esos valores. Consulte [Ajustar nivel de esfuerzo](/es/model-config#adjust-effort-level) para modelos compatibles | `"xhigh"` |192| `effortLevel` | Persistir el [nivel de esfuerzo](/es/model-config#adjust-effort-level) entre sesiones. Acepta `"low"`, `"medium"`, `"high"`, o `"xhigh"`. Se escribe automáticamente cuando ejecuta `/effort` con uno de esos valores. Consulte [Ajustar nivel de esfuerzo](/es/model-config#adjust-effort-level) para modelos compatibles | `"xhigh"` |

550 },554 },

551 "extraKnownMarketplaces": {555 "extraKnownMarketplaces": {

552 "acme-tools": {556 "acme-tools": {

557 "source": {

553 "source": "github",558 "source": "github",

554 "repo": "acme-corp/claude-plugins"559 "repo": "acme-corp/claude-plugins"

555 }560 }

556 }561 }

562 }

557}563}

558```564```

559 565

568* **Configuraciones locales** (`.claude/settings.local.json`): Anulaciones por máquina (no confirmadas)574* **Configuraciones locales** (`.claude/settings.local.json`): Anulaciones por máquina (no confirmadas)

569* **Configuraciones administradas** (`managed-settings.json`): Anulaciones de política a nivel de organización que bloquean la instalación en todos los ámbitos y ocultan el plugin del marketplace575* **Configuraciones administradas** (`managed-settings.json`): Anulaciones de política a nivel de organización que bloquean la instalación en todos los ámbitos y ocultan el plugin del marketplace

570 576

577<Note>

578 Las configuraciones de proyecto tienen precedencia sobre las configuraciones de usuario, por lo que establecer un plugin en `false` en `~/.claude/settings.json` no deshabilita un plugin que la `.claude/settings.json` del proyecto habilita. Para optar por no participar en un plugin habilitado por el proyecto en su máquina, establézcalo en `false` en `.claude/settings.local.json` en su lugar.

579

580 Los plugins forzados a estar habilitados por configuraciones administradas no pueden deshabilitarse de esta manera, ya que las configuraciones administradas anulan las configuraciones locales.

581</Note>

582

571**Ejemplo**:583**Ejemplo**:

572 584

573```json theme={null}585```json theme={null}

659* Solo disponible en configuraciones administradas (`managed-settings.json`)671* Solo disponible en configuraciones administradas (`managed-settings.json`)

660* No puede ser anulada por configuraciones de usuario o proyecto (precedencia más alta)672* No puede ser anulada por configuraciones de usuario o proyecto (precedencia más alta)

661* Se aplica ANTES de operaciones de red/sistema de archivos (las fuentes bloqueadas nunca se ejecutan)673* Se aplica ANTES de operaciones de red/sistema de archivos (las fuentes bloqueadas nunca se ejecutan)

662* Usa coincidencia exacta para especificaciones de fuente (incluyendo `ref`, `path` para fuentes de git), excepto `hostPattern`, que usa coincidencia regex674* Usa coincidencia exacta para especificaciones de fuente (incluyendo `ref`, `path` para fuentes de git), excepto `hostPattern` y `pathPattern`, que usan coincidencia regex

663 675

664**Comportamiento de lista blanca**:676**Comportamiento de lista blanca**:

665 677

669 681

670**Todos los tipos de fuente admitidos**:682**Todos los tipos de fuente admitidos**:

671 683

672La lista blanca admite múltiples tipos de fuente de marketplace. La mayoría de las fuentes usan coincidencia exacta, mientras que `hostPattern` usa coincidencia regex contra el host del marketplace.684La lista blanca admite múltiples tipos de fuente de marketplace. La mayoría de las fuentes usan coincidencia exacta, mientras que `hostPattern` y `pathPattern` usan coincidencia regex contra el host del marketplace y la ruta del sistema de archivos respectivamente.

673 685

6741. **Repositorios de GitHub**:6861. **Repositorios de GitHub**:

675 687

749* `url`: extrae nombre de host de la URL761* `url`: extrae nombre de host de la URL

750* `npm`, `file`, `directory`: no admitido para coincidencia de patrón de host762* `npm`, `file`, `directory`: no admitido para coincidencia de patrón de host

751 763

7648. **Coincidencia de patrón de ruta**:

765

766```json theme={null}

767{ "source": "pathPattern", "pathPattern": "^/opt/approved/" }

768{ "source": "pathPattern", "pathPattern": ".*" }

769```

770

771Campos: `pathPattern` (requerido: patrón regex coincidido contra el campo `path` de fuentes `file` y `directory`)

772

773Use coincidencia de patrón de ruta para permitir marketplaces basados en sistema de archivos junto con restricciones `hostPattern` para fuentes de red. Establezca `".*"` para permitir todas las rutas locales, o un patrón más estrecho para restringir a directorios específicos.

774

752**Ejemplos de configuración**:775**Ejemplos de configuración**:

753 776

754Ejemplo: permitir solo marketplaces específicos:777Ejemplo: permitir solo marketplaces específicos:

sub-agents.md +36 −11

Details

51 </Tab>51 </Tab>

52 52

53 <Tab title="Plan">53 <Tab title="Plan">

~~54 Un agente de investigación utilizado durante [plan mode](/es/common-workflows#use-plan-mode-for-safe-code-analysis) para recopilar contexto antes de presentar un plan.~~54 Un agente de investigación utilizado durante [plan mode](/es/permission-modes#analyze-before-you-edit-with-plan-mode) para recopilar contexto antes de presentar un plan.

55 55

56 * **Modelo**: Hereda de la conversación principal56 * **Modelo**: Hereda de la conversación principal

57 * **Herramientas**: Herramientas de solo lectura (acceso denegado a herramientas Write y Edit)57 * **Herramientas**: Herramientas de solo lectura (acceso denegado a herramientas Write y Edit)

77 | :---------------- | :----- | :-------------------------------------------------------------- |77 | :---------------- | :----- | :-------------------------------------------------------------- |

80 </Tab>80 </Tab>

81</Tabs>81</Tabs>

82 82

180 180

181**Los subagentes definidos por CLI** se pasan como JSON al lanzar Claude Code. Existen solo para esa sesión y no se guardan en disco, lo que los hace útiles para pruebas rápidas o scripts de automatización. Puede definir múltiples subagentes en una única llamada `--agents`:181**Los subagentes definidos por CLI** se pasan como JSON al lanzar Claude Code. Existen solo para esa sesión y no se guardan en disco, lo que los hace útiles para pruebas rápidas o scripts de automatización. Puede definir múltiples subagentes en una única llamada `--agents`:

182 182

183```bash theme={null}183<Tabs>

184claude --agents '{184 <Tab title="macOS, Linux, WSL">

185 ```bash theme={null}

186 claude --agents '{

185 "code-reviewer": {187 "code-reviewer": {

186 "description": "Expert code reviewer. Use proactively after code changes.",188 "description": "Expert code reviewer. Use proactively after code changes.",

187 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",189 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

192 "description": "Debugging specialist for errors and test failures.",194 "description": "Debugging specialist for errors and test failures.",

193 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."195 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

194 }196 }

195}'197 }'

196```198 ```

199 </Tab>

200

201 <Tab title="Windows PowerShell">

202 ```powershell theme={null}

203 claude --agents @'

204 {

205 "code-reviewer": {

206 "description": "Expert code reviewer. Use proactively after code changes.",

207 "prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",

208 "tools": ["Read", "Grep", "Glob", "Bash"],

209 "model": "sonnet"

210 },

211 "debugger": {

212 "description": "Debugging specialist for errors and test failures.",

213 "prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."

214 }

215 }

216 '@

217 ```

218 </Tab>

219</Tabs>

197 220

198La bandera `--agents` acepta JSON con los mismos campos de [frontmatter](#supported-frontmatter-fields) que los subagentes basados en archivos: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation` y `color`. Use `prompt` para el mensaje del sistema, equivalente al cuerpo markdown en subagentes basados en archivos.221La bandera `--agents` acepta JSON con los mismos campos de [frontmatter](#supported-frontmatter-fields) que los subagentes basados en archivos: `description`, `prompt`, `tools`, `disallowedTools`, `model`, `permissionMode`, `mcpServers`, `hooks`, `maxTurns`, `skills`, `initialPrompt`, `memory`, `effort`, `background`, `isolation` y `color`. Use `prompt` para el mensaje del sistema, equivalente al cuerpo markdown en subagentes basados en archivos.

199 222

212Los archivos de subagentes usan frontmatter YAML para configuración, seguido del mensaje del sistema en Markdown:235Los archivos de subagentes usan frontmatter YAML para configuración, seguido del mensaje del sistema en Markdown:

213 236

214<Note>237<Note>

215 Los subagentes se cargan al inicio de la sesión. Si crea un subagente agregando manualmente un archivo, reinicie su sesión o use `/agents` para cargarlo inmediatamente.238 Los subagentes se cargan al inicio de la sesión. Si agrega o edita un archivo de subagente directamente en el disco, reinicie su sesión para cargarlo. Los subagentes creados a través de la interfaz `/agents` tienen efecto inmediatamente sin necesidad de reinicio.

216</Note>239</Note>

217 240

218```markdown theme={null}241```markdown theme={null}

250| `memory` | No | [Alcance de memoria persistente](#enable-persistent-memory): `user`, `project`, o `local`. Habilita aprendizaje entre sesiones |273| `memory` | No | [Alcance de memoria persistente](#enable-persistent-memory): `user`, `project`, o `local`. Habilita aprendizaje entre sesiones |

251| `background` | No | Establecer en `true` para ejecutar siempre este subagente como una [tarea de fondo](#run-subagents-in-foreground-or-background). Por defecto: `false` |274| `background` | No | Establecer en `true` para ejecutar siempre este subagente como una [tarea de fondo](#run-subagents-in-foreground-or-background). Por defecto: `false` |

252| `effort` | No | Nivel de esfuerzo cuando este subagente está activo. Anula el nivel de esfuerzo de la sesión. Por defecto: hereda de la sesión. Opciones: `low`, `medium`, `high`, `xhigh`, `max`; los niveles disponibles dependen del modelo |275| `effort` | No | Nivel de esfuerzo cuando este subagente está activo. Anula el nivel de esfuerzo de la sesión. Por defecto: hereda de la sesión. Opciones: `low`, `medium`, `high`, `xhigh`, `max`; los niveles disponibles dependen del modelo |

253| `isolation` | No | Establecer en `worktree` para ejecutar el subagente en un [git worktree](/es/common-workflows#run-parallel-claude-code-sessions-with-git-worktrees) temporal, dándole una copia aislada del repositorio. El worktree se limpia automáticamente si el subagente no realiza cambios |276| `isolation` | No | Establecer en `worktree` para ejecutar el subagente en un [git worktree](/es/worktrees) temporal, dándole una copia aislada del repositorio. El worktree se limpia automáticamente si el subagente no realiza cambios |

254| `color` | No | Color de visualización para el subagente en la lista de tareas y transcripción. Acepta `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, o `cyan` |277| `color` | No | Color de visualización para el subagente en la lista de tareas y transcripción. Acepta `red`, `blue`, `green`, `yellow`, `purple`, `orange`, `pink`, o `cyan` |

255| `initialPrompt` | No | Se envía automáticamente como el primer turno de usuario cuando este agente se ejecuta como el agente de sesión principal (a través de `--agent` o la configuración `agent`). Se procesan [comandos](/es/commands) y [skills](/es/skills). Se antepone a cualquier mensaje proporcionado por el usuario |278| `initialPrompt` | No | Se envía automáticamente como el primer turno de usuario cuando este agente se ejecuta como el agente de sesión principal (a través de `--agent` o la configuración `agent`). Se procesan [comandos](/es/commands) y [skills](/es/skills). Se antepone a cualquier mensaje proporcionado por el usuario |

256 279

484exit 0507exit 0

485```508```

486 509

487Consulte [Hook input](/es/hooks#pretooluse-input) para el esquema de entrada completo y [códigos de salida](/es/hooks#exit-code-output) para cómo los códigos de salida afectan el comportamiento.510Consulte [Hook input](/es/hooks#pretooluse-input) para el esquema de entrada completo y [códigos de salida](/es/hooks#exit-code-output) para cómo los códigos de salida afectan el comportamiento. En Windows, escriba scripts de hook en PowerShell y agregue `shell: powershell` a la entrada del hook como se muestra en [ejecutar hooks en PowerShell](/es/hooks#windows-powershell-tool).

488 511

489#### Deshabilitar subagentes específicos512#### Deshabilitar subagentes específicos

490 513

994exit 01017exit 0

995```1018```

996 1019

997Haga el script ejecutable:1020En macOS y Linux, haga el script ejecutable:

998 1021

999```bash theme={null}1022```bash theme={null}

1000chmod +x ./scripts/validate-readonly-query.sh1023chmod +x ./scripts/validate-readonly-query.sh

1001```1024```

1002 1025

1003El hook recibe JSON a través de stdin con el comando Bash en `tool_input.command`. El código de salida 2 bloquea la operación y alimenta el mensaje de error de vuelta a Claude. Consulte [Hooks](/es/hooks#exit-code-output) para detalles sobre códigos de salida y [Hook input](/es/hooks#pretooluse-input) para el esquema de entrada completo.1026En Windows, escriba el script de validación en PowerShell y agregue `shell: powershell` a la entrada del hook. Consulte [ejecutar hooks en PowerShell](/es/hooks#windows-powershell-tool).

1027

1028El hook recibe JSON a través de stdin con el comando Bash en `tool_input.command`. El código de salida 2 bloquea la operación y alimenta el mensaje de error de vuelta a Claude. Consulte [Hooks](/es/hooks#exit-code-output) para detalles sobre códigos de salida e [Hook input](/es/hooks#pretooluse-input) para el esquema de entrada completo.

1004 1029

1005## Próximos pasos1030## Próximos pasos

1006 1031

vs-code.md +13 −3

Details

95* **Modos de permiso**: haz clic en el indicador de modo en la parte inferior del cuadro de mensaje para cambiar de modo. En modo normal, Claude solicita permiso antes de cada acción. En Plan Mode, Claude describe lo que hará y espera aprobación antes de realizar cambios. VS Code abre automáticamente el plan como un documento markdown completo donde puedes agregar comentarios en línea para dar retroalimentación antes de que Claude comience. En modo de aceptación automática, Claude realiza ediciones sin preguntar. Establece el valor predeterminado en la configuración de VS Code en `claudeCode.initialPermissionMode`.95* **Modos de permiso**: haz clic en el indicador de modo en la parte inferior del cuadro de mensaje para cambiar de modo. En modo normal, Claude solicita permiso antes de cada acción. En Plan Mode, Claude describe lo que hará y espera aprobación antes de realizar cambios. VS Code abre automáticamente el plan como un documento markdown completo donde puedes agregar comentarios en línea para dar retroalimentación antes de que Claude comience. En modo de aceptación automática, Claude realiza ediciones sin preguntar. Establece el valor predeterminado en la configuración de VS Code en `claudeCode.initialPermissionMode`.

96* **Menú de comandos**: haz clic en `/` o escribe `/` para abrir el menú de comandos. Las opciones incluyen adjuntar archivos, cambiar modelos, alternar pensamiento extendido, ver uso del plan (`/usage`) e iniciar una sesión de [Control remoto](/es/remote-control) (`/remote-control`). La sección Personalizar proporciona acceso a MCP servers, hooks, memoria, permisos y plugins. Los elementos con un icono de terminal se abren en la terminal integrada.96* **Menú de comandos**: haz clic en `/` o escribe `/` para abrir el menú de comandos. Las opciones incluyen adjuntar archivos, cambiar modelos, alternar pensamiento extendido, ver uso del plan (`/usage`) e iniciar una sesión de [Control remoto](/es/remote-control) (`/remote-control`). La sección Personalizar proporciona acceso a MCP servers, hooks, memoria, permisos y plugins. Los elementos con un icono de terminal se abren en la terminal integrada.

97* **Indicador de contexto**: el cuadro de mensaje muestra cuánto de la ventana de contexto de Claude estás utilizando. Claude se compacta automáticamente cuando es necesario, o puedes ejecutar `/compact` manualmente.97* **Indicador de contexto**: el cuadro de mensaje muestra cuánto de la ventana de contexto de Claude estás utilizando. Claude se compacta automáticamente cuando es necesario, o puedes ejecutar `/compact` manualmente.

98* **Pensamiento extendido**: permite que Claude dedique más tiempo a razonar sobre problemas complejos. Actívalo a través del menú de comandos (`/`). El razonamiento de Claude aparece en la conversación como bloques contraídos: haz clic en un bloque para leerlo, o presiona `Ctrl+O` para expandir o contraer cada bloque de pensamiento en la sesión. Consulta [Pensamiento extendido](/es/common-workflows#usar-pensamiento-extendido-thinking-mode) para obtener más detalles.98* **Pensamiento extendido**: permite que Claude dedique más tiempo a razonar sobre problemas complejos. Actívalo a través del menú de comandos (`/`). El razonamiento de Claude aparece en la conversación como bloques contraídos: haz clic en un bloque para leerlo, o presiona `Ctrl+O` para expandir o contraer cada bloque de pensamiento en la sesión. Consulta [Pensamiento extendido](/es/model-config#extended-thinking) para obtener más detalles.

99* **Entrada multilínea**: presiona `Shift+Enter` para agregar una nueva línea sin enviar. Esto también funciona en la entrada de texto libre "Otro" de los diálogos de preguntas.99* **Entrada multilínea**: presiona `Shift+Enter` para agregar una nueva línea sin enviar. Esto también funciona en la entrada de texto libre "Otro" de los diálogos de preguntas.

100 100

101### Referenciar archivos y carpetas101### Referenciar archivos y carpetas

115 115

116### Reanudar conversaciones pasadas116### Reanudar conversaciones pasadas

117 117

118Haz clic en el botón **Historial de sesiones** en la parte superior del panel de Claude Code para acceder a tu historial de conversaciones. Puedes buscar por palabra clave o examinar por tiempo (Hoy, Ayer, Últimos 7 días, etc.). Haz clic en cualquier conversación para reanudarla con el historial de mensajes completo. Las nuevas sesiones reciben títulos generados por IA basados en tu primer mensaje. Pasa el cursor sobre una sesión para revelar acciones de cambio de nombre y eliminación: cambia el nombre para darle un título descriptivo, o elimina para borrarlo de la lista. Para más información sobre cómo reanudar sesiones, consulta [Flujos de trabajo comunes](/es/common-workflows#reanudar-conversaciones-anteriores).118Haz clic en el botón **Historial de sesiones** en la parte superior del panel de Claude Code para acceder a tu historial de conversaciones. Puedes buscar por palabra clave o examinar por tiempo (Hoy, Ayer, Últimos 7 días, etc.). Haz clic en cualquier conversación para reanudarla con el historial de mensajes completo. Las nuevas sesiones reciben títulos generados por IA basados en tu primer mensaje. Pasa el cursor sobre una sesión para revelar acciones de cambio de nombre y eliminación: cambia el nombre para darle un título descriptivo, o elimina para borrarlo de la lista. Para más información sobre cómo reanudar sesiones, consulta [Administrar sesiones](/es/sessions).

119 119

120### Reanudar sesiones remotas desde Claude.ai120### Reanudar sesiones remotas desde Claude.ai

121 121

399claude --worktree feature-auth399claude --worktree feature-auth

400```400```

401 401

402Cada worktree mantiene un estado de archivo independiente mientras comparte el historial de git. Esto evita que las instancias de Claude interfieran entre sí cuando trabajan en diferentes tareas. Para más detalles, consulta [Ejecutar sesiones paralelas de Claude Code con Git worktrees](/es/common-workflows#ejecutar-sesiones-paralelas-de-claude-code-con-git-worktrees).402Cada worktree mantiene un estado de archivo independiente mientras comparte el historial de git. Esto evita que las instancias de Claude interfieran entre sí cuando trabajan en diferentes tareas. Para más detalles, consulta [Ejecutar sesiones paralelas con Git worktrees](/es/worktrees).

403 403

404## Usar proveedores de terceros404## Usar proveedores de terceros

405 405

476 476

477Alternativamente, haz clic en "✱ Claude Code" en la **Barra de estado** (esquina inferior derecha). Esto funciona incluso sin un archivo abierto. También puedes usar la **Paleta de comandos** (`Cmd+Shift+P` / `Ctrl+Shift+P`) y escribir "Claude Code".477Alternativamente, haz clic en "✱ Claude Code" en la **Barra de estado** (esquina inferior derecha). Esto funciona incluso sin un archivo abierto. También puedes usar la **Paleta de comandos** (`Cmd+Shift+P` / `Ctrl+Shift+P`) y escribir "Claude Code".

478 478

479### Cmd+Esc no hace nada en macOS

480

481En macOS Tahoe y posterior, el atajo del sistema Game Overlay está vinculado a `Cmd+Esc` de forma predeterminada e intercepta la pulsación de tecla antes de que llegue a VS Code. Para liberar el atajo:

482

4831. Abre Configuración del sistema

4842. Ve a Teclado, luego Atajos de teclado, luego Controladores de juegos

4853. Desactiva la casilla de verificación Game Overlay

486

487Alternativamente, vuelve a vincular la extensión a una tecla diferente: abre el editor de [Atajos de teclado](https://code.visualstudio.com/docs/configure/keybindings) de VS Code (`Cmd+K Cmd+S`), busca `Claude Code: Focus input`, y asigna un nuevo atajo.

488

479### Claude Code nunca responde489### Claude Code nunca responde

480 490

481Si Claude Code no responde a tus mensajes:491Si Claude Code no responde a tus mensajes:

Documentation 2026-05-04 22:58 UTC to 2026-05-05 23:00 UTC