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

# Revertir cambios de archivos con checkpointing

> Rastrear cambios de archivos durante sesiones de agente y restaurar archivos a cualquier estado anterior

El checkpointing de archivos rastrea las modificaciones de archivos realizadas a través de las herramientas [Write](/docs/es/tools-reference#write-tool-behavior), [Edit](/docs/es/tools-reference#edit-tool-behavior) y [NotebookEdit](/docs/es/tools-reference#notebookedit-tool-behavior) durante una sesión de agente, lo que le permite revertir archivos a cualquier estado anterior. Para ver cómo una reversión restaura un archivo, salte al [ejemplo interactivo](#try-it-out).

<Warning>
  Solo se rastrean los cambios realizados a través de las herramientas Write, Edit y NotebookEdit. Los cambios realizados a través de comandos Bash (como `echo > file.txt` o `sed -i`) no se capturan en el sistema de checkpoint, y tampoco las ediciones que aplica un [subagente](/docs/es/agent-sdk/subagents), excepto una [skill con `context: fork`](/docs/es/skills#run-skills-in-a-subagent) que se ejecuta en primer plano.
</Warning>

<h2 id="how-checkpointing-works">
  Cómo funciona el checkpointing
</h2>

Cuando habilita el checkpointing de archivos, el SDK crea copias de seguridad de archivos antes de modificarlos a través de las herramientas Write, Edit o NotebookEdit. Los mensajes de usuario en el flujo de respuesta incluyen un UUID de checkpoint que puede usar como punto de restauración.

<Note>
  La reversión de archivos restaura archivos en disco a un estado anterior. No revierte la conversación en sí. El historial de conversación y el contexto permanecen intactos después de llamar a `rewindFiles()` (TypeScript) o `rewind_files()` (Python).
</Note>

Cuando revierte a un checkpoint, Claude Code elimina los archivos que creó y restaura los archivos que modificó a su contenido en ese punto. Claude Code omite una ruta rastreada que es un enlace simbólico, enlace físico u otro archivo no regular. También omite un archivo rastreado cuyo directorio padre ya no se resuelve a su ubicación en el momento del checkpoint, o cuya copia de seguridad no puede leer de forma segura. [`RewindFilesResult`](/docs/es/agent-sdk/typescript#rewindfilesresult) cuenta cada ruta omitida en su campo `skippedLinks`. Omitir requiere Claude Code v2.1.216 o posterior; antes de v2.1.216, una reversión escribía y eliminaba a través de enlaces en rutas rastreadas.

<h2 id="implement-checkpointing">
  Implementar checkpointing
</h2>

Para usar el checkpointing de archivos, habilítelo en sus opciones, capture UUIDs de checkpoint del flujo de respuesta, luego llame a `rewindFiles()` (TypeScript) o `rewind_files()` (Python) cuando necesite restaurar.

Los ejemplos en esta sección utilizan el mensaje "Refactor the authentication module". Ejecútelos en un proyecto que contenga un módulo de autenticación, o cambie el mensaje para nombrar archivos que existan en su proyecto, para que pueda ver cambios de archivos y ver cómo la reversión los restaura.

Este ejemplo habilita checkpointing, captura el UUID de checkpoint e ID de sesión del flujo de respuesta, luego reanuda la sesión más tarde para revertir archivos. Los comentarios numerados del ejemplo coinciden con los pasos que siguen.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from claude_agent_sdk import (
      ClaudeSDKClient,
      ClaudeAgentOptions,
      UserMessage,
      ResultMessage,
  )


  async def main():
      # Step 1: Enable checkpointing
      options = ClaudeAgentOptions(
          enable_file_checkpointing=True,
          permission_mode="acceptEdits",  # Auto-accept file edits without prompting
          extra_args={
              "replay-user-messages": None
          },  # Required to receive checkpoint UUIDs in the response stream
      )

      checkpoint_id = None
      session_id = None

      # Run the query and capture checkpoint UUID and session ID
      async with ClaudeSDKClient(options) as client:
          await client.query("Refactor the authentication module")

          # Step 2: Capture checkpoint UUID from the first user message
          async for message in client.receive_response():
              if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
                  checkpoint_id = message.uuid
              if isinstance(message, ResultMessage) and not session_id:
                  session_id = message.session_id

      # Step 3: Later, rewind by resuming the session with an empty prompt
      if checkpoint_id and session_id:
          async with ClaudeSDKClient(
              ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
          ) as client:
              await client.query("")  # Empty prompt to open the connection
              async for message in client.receive_response():
                  await client.rewind_files(checkpoint_id)
                  break
          print(f"Rewound to checkpoint: {checkpoint_id}")


  asyncio.run(main())
  ```

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

  async function main() {
    // Step 1: Enable checkpointing
    const opts = {
      enableFileCheckpointing: true,
      permissionMode: "acceptEdits" as const, // Auto-accept file edits without prompting
      extraArgs: { "replay-user-messages": null } // Required to receive checkpoint UUIDs in the response stream
    };

    const response = query({
      prompt: "Refactor the authentication module",
      options: opts
    });

    let checkpointId: string | undefined;
    let sessionId: string | undefined;

    // Step 2: Capture checkpoint UUID from the first user message
    try {
      for await (const message of response) {
        if (message.type === "user" && message.uuid && !checkpointId) {
          checkpointId = message.uuid;
        }
        if ("session_id" in message && !sessionId) {
          sessionId = message.session_id;
        }
      }
    } catch (error) {
      // A single-shot query() throws after yielding an error result. If the
      // failure was an error result, sessionId and checkpointId were already
      // captured by the loop above; connection or process failures yield no
      // result message.
      console.error(`Session ended with an error: ${error}`);
    }

    // Step 3: Later, rewind by resuming the session with an empty prompt
    if (checkpointId && sessionId) {
      const rewindQuery = query({
        prompt: "", // Empty prompt to open the connection
        options: { ...opts, resume: sessionId }
      });

      for await (const msg of rewindQuery) {
        await rewindQuery.rewindFiles(checkpointId);
        break;
      }
      console.log(`Rewound to checkpoint: ${checkpointId}`);
    }
  }

  main();
  ```
</CodeGroup>

<Steps>
  <Step title="Habilitar checkpointing">
    Configure sus opciones de SDK para habilitar checkpointing y recibir UUIDs de checkpoint:

    | Opción | Python | TypeScript | Descripción |
    | - | - | - | - |
    | Habilitar checkpointing | `enable_file_checkpointing=True` | `enableFileCheckpointing: true` | Rastrea cambios de archivos para reversión |
    | Recibir UUIDs de checkpoint | `extra_args={"replay-user-messages": None}` | `extraArgs: { 'replay-user-messages': null }` | Requerido para obtener UUIDs de mensajes de usuario en el flujo |

    El ejemplo principal bajo [Implementar checkpointing](#implement-checkpointing) también establece el modo de permiso en `acceptEdits`, que aprueba los cambios de archivos del agente sin un mensaje. Para más información, consulte [Modos de permiso](/docs/es/agent-sdk/permissions#permission-modes).
  </Step>

  <Step title="Capturar UUID de checkpoint e ID de sesión">
    Con la opción `replay-user-messages` establecida, cada mensaje de usuario en el flujo de respuesta tiene un UUID que sirve como checkpoint.

    Para la mayoría de los casos de uso, capture el UUID del primer mensaje de usuario (`message.uuid`); revertir a él restaura todos los archivos a su estado original. Para almacenar múltiples checkpoints y revertir a estados intermedios, consulte [Múltiples puntos de restauración](#multiple-restore-points).

    Capturar el ID de sesión (`message.session_id`) es opcional; solo lo necesita si desea revertir más tarde, después de que se complete el flujo. Si está llamando a `rewindFiles()` inmediatamente mientras aún procesa mensajes (como lo hace el ejemplo en [Checkpoint antes de operaciones arriesgadas](#checkpoint-before-risky-operations)), puede omitir la captura del ID de sesión.
  </Step>

  <Step title="Revertir archivos">
    Para revertir después de que se complete el flujo, reanude la sesión con un mensaje vacío y llame a `rewind_files()` (Python) o `rewindFiles()` (TypeScript) con su UUID de checkpoint. Habilite checkpointing en las opciones de la sesión reanudada también, y llame a revertir desde dentro del bucle de respuesta. También puede revertir durante el flujo. Consulte [Checkpoint antes de operaciones arriesgadas](#checkpoint-before-risky-operations) para ese patrón.

    Si captura el ID de sesión y el ID de checkpoint, también puede revertir desde la CLI. Este comando requiere el ejecutable `claude`, que viene de [instalar Claude Code](/docs/es/setup). El SDK habilita checkpointing para usted, pero cuando ejecuta `claude -p` directamente debe establecer la variable de entorno `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING`:

    ```bash theme={null}
    CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>
    ```

    La bandera `--rewind-files` no aparece en la salida de `claude --help`, pero la CLI la acepta como se muestra. Cuando la reversión tiene éxito, el comando imprime `Files rewound to state at message <checkpoint-uuid>` y sale sin enviar un mensaje.
  </Step>
</Steps>

<h2 id="common-patterns">
  Patrones comunes
</h2>

Estos patrones muestran diferentes formas de capturar y usar UUIDs de checkpoint según su caso de uso.

<h3 id="checkpoint-before-risky-operations">
  Checkpoint antes de operaciones arriesgadas
</h3>

Este patrón mantiene solo el UUID de checkpoint más reciente, actualizándolo antes de cada turno del agente. Si algo sale mal durante el procesamiento, puede revertir inmediatamente al último estado seguro y salir del bucle.

Antes de ejecutar este ejemplo, reemplace `your_revert_condition` (Python) o `yourRevertCondition` (TypeScript) con su propia verificación, como detección de errores o un fallo de validación; el marcador de posición no está definido en el ejemplo.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions, UserMessage


  async def main():
      options = ClaudeAgentOptions(
          enable_file_checkpointing=True,
          permission_mode="acceptEdits",
          extra_args={"replay-user-messages": None},
      )

      safe_checkpoint = None

      async with ClaudeSDKClient(options) as client:
          await client.query("Refactor the authentication module")

          async for message in client.receive_response():
              # Update checkpoint before each agent turn starts
              # This overwrites the previous checkpoint. Only keep the latest
              if isinstance(message, UserMessage) and message.uuid:
                  safe_checkpoint = message.uuid

              # Decide when to revert based on your own logic
              # For example: error detection, validation failure, or user input
              if your_revert_condition and safe_checkpoint:
                  await client.rewind_files(safe_checkpoint)
                  # Exit the loop after rewinding, files are restored
                  break


  asyncio.run(main())
  ```

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

  async function main() {
    const response = query({
      prompt: "Refactor the authentication module",
      options: {
        enableFileCheckpointing: true,
        permissionMode: "acceptEdits" as const,
        extraArgs: { "replay-user-messages": null }
      }
    });

    let safeCheckpoint: string | undefined;

    for await (const message of response) {
      // Update checkpoint before each agent turn starts
      // This overwrites the previous checkpoint. Only keep the latest
      if (message.type === "user" && message.uuid) {
        safeCheckpoint = message.uuid;
      }

      // Decide when to revert based on your own logic
      // For example: error detection, validation failure, or user input
      if (yourRevertCondition && safeCheckpoint) {
        await response.rewindFiles(safeCheckpoint);
        // Exit the loop after rewinding, files are restored
        break;
      }
    }
  }

  main();
  ```
</CodeGroup>

<h3 id="multiple-restore-points">
  Múltiples puntos de restauración
</h3>

Si Claude realiza cambios en múltiples turnos, es posible que desee revertir a un punto específico en lugar de volver completamente. Por ejemplo, si Claude refactoriza un archivo en el turno uno y agrega pruebas en el turno dos, es posible que desee mantener la refactorización pero deshacer las pruebas.

Este patrón almacena todos los UUIDs de checkpoint en una matriz con metadatos. Después de que se complete la sesión, puede revertir a cualquier checkpoint anterior:

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from dataclasses import dataclass
  from datetime import datetime
  from claude_agent_sdk import (
      ClaudeSDKClient,
      ClaudeAgentOptions,
      UserMessage,
      ResultMessage,
  )


  # Store checkpoint metadata for better tracking
  @dataclass
  class Checkpoint:
      id: str
      description: str
      timestamp: datetime


  async def main():
      options = ClaudeAgentOptions(
          enable_file_checkpointing=True,
          permission_mode="acceptEdits",
          extra_args={"replay-user-messages": None},
      )

      checkpoints = []
      session_id = None

      async with ClaudeSDKClient(options) as client:
          await client.query("Refactor the authentication module")

          async for message in client.receive_response():
              if isinstance(message, UserMessage) and message.uuid:
                  checkpoints.append(
                      Checkpoint(
                          id=message.uuid,
                          description=f"After turn {len(checkpoints) + 1}",
                          timestamp=datetime.now(),
                      )
                  )
              if isinstance(message, ResultMessage) and not session_id:
                  session_id = message.session_id

      # Later: rewind to any checkpoint by resuming the session
      if checkpoints and session_id:
          target = checkpoints[0]  # Pick any checkpoint
          async with ClaudeSDKClient(
              ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
          ) as client:
              await client.query("")  # Empty prompt to open the connection
              async for message in client.receive_response():
                  await client.rewind_files(target.id)
                  break
          print(f"Rewound to: {target.description}")


  asyncio.run(main())
  ```

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

  // Store checkpoint metadata for better tracking
  interface Checkpoint {
    id: string;
    description: string;
    timestamp: Date;
  }

  async function main() {
    const opts = {
      enableFileCheckpointing: true,
      permissionMode: "acceptEdits" as const,
      extraArgs: { "replay-user-messages": null }
    };

    const response = query({
      prompt: "Refactor the authentication module",
      options: opts
    });

    const checkpoints: Checkpoint[] = [];
    let sessionId: string | undefined;

    try {
      for await (const message of response) {
        if (message.type === "user" && message.uuid) {
          checkpoints.push({
            id: message.uuid,
            description: `After turn ${checkpoints.length + 1}`,
            timestamp: new Date()
          });
        }
        if ("session_id" in message && !sessionId) {
          sessionId = message.session_id;
        }
      }
    } catch (error) {
      // A single-shot query() throws after yielding an error result. If the
      // failure was an error result, sessionId and the checkpoints array were
      // already populated by the loop above; connection or process failures
      // yield no result message.
      console.error(`Session ended with an error: ${error}`);
    }

    // Later: rewind to any checkpoint by resuming the session
    if (checkpoints.length > 0 && sessionId) {
      const target = checkpoints[0]; // Pick any checkpoint
      const rewindQuery = query({
        prompt: "", // Empty prompt to open the connection
        options: { ...opts, resume: sessionId }
      });

      for await (const msg of rewindQuery) {
        await rewindQuery.rewindFiles(target.id);
        break;
      }
      console.log(`Rewound to: ${target.description}`);
    }
  }

  main();
  ```
</CodeGroup>

<h2 id="try-it-out">
  Pruébelo
</h2>

Este ejemplo completo crea un pequeño archivo de utilidad, hace que el agente agregue comentarios de documentación, le muestra los cambios, luego pregunta si desea revertir.

Antes de comenzar, asegúrese de tener el [Claude Agent SDK instalado](/docs/es/agent-sdk/quickstart).

<Steps>
  <Step title="Crear un archivo de prueba">
    Cree un nuevo archivo llamado `utils.py` (Python) o `utils.ts` (TypeScript) y pegue el siguiente código:

    <CodeGroup>
      ```python utils.py theme={null}
      def add(a, b):
          return a + b


      def subtract(a, b):
          return a - b


      def multiply(a, b):
          return a * b


      def divide(a, b):
          if b == 0:
              raise ValueError("Cannot divide by zero")
          return a / b
      ```

      ```typescript utils.ts theme={null}
      export function add(a: number, b: number): number {
        return a + b;
      }

      export function subtract(a: number, b: number): number {
        return a - b;
      }

      export function multiply(a: number, b: number): number {
        return a * b;
      }

      export function divide(a: number, b: number): number {
        if (b === 0) {
          throw new Error("Cannot divide by zero");
        }
        return a / b;
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Ejecutar el ejemplo interactivo">
    Cree un nuevo archivo llamado `try_checkpointing.py` (Python) o `try_checkpointing.ts` (TypeScript) en el mismo directorio que su archivo de utilidad, y pegue el siguiente código.

    Este script le pide a Claude que agregue comentarios de documentación a su archivo de utilidad, luego le da la opción de revertir y restaurar el original.

    <CodeGroup>
      ```python try_checkpointing.py theme={null}
      import asyncio
      from claude_agent_sdk import (
          ClaudeSDKClient,
          ClaudeAgentOptions,
          UserMessage,
          ResultMessage,
      )


      async def main():
          # Configure the SDK with checkpointing enabled
          # - enable_file_checkpointing: Track file changes for rewinding
          # - permission_mode: Auto-accept file edits without prompting
          # - extra_args: Required to receive user message UUIDs in the stream
          options = ClaudeAgentOptions(
              enable_file_checkpointing=True,
              permission_mode="acceptEdits",
              extra_args={"replay-user-messages": None},
          )

          checkpoint_id = None  # Store the user message UUID for rewinding
          session_id = None  # Store the session ID for resuming

          print("Running agent to add doc comments to utils.py...\n")

          # Run the agent and capture checkpoint data from the response stream
          async with ClaudeSDKClient(options) as client:
              await client.query("Add doc comments to utils.py")

              async for message in client.receive_response():
                  # Capture the first user message UUID - this is our restore point
                  if isinstance(message, UserMessage) and message.uuid and not checkpoint_id:
                      checkpoint_id = message.uuid
                  # Capture the session ID so we can resume later
                  if isinstance(message, ResultMessage):
                      session_id = message.session_id

          print("Done! Open utils.py to see the added doc comments.\n")

          # Ask the user if they want to rewind the changes
          if checkpoint_id and session_id:
              response = input("Rewind to remove the doc comments? (y/n): ")

              if response.lower() == "y":
                  # Resume the session with an empty prompt, then rewind
                  async with ClaudeSDKClient(
                      ClaudeAgentOptions(enable_file_checkpointing=True, resume=session_id)
                  ) as client:
                      await client.query("")  # Empty prompt opens the connection
                      async for message in client.receive_response():
                          await client.rewind_files(checkpoint_id)  # Restore files
                          break

                  print(
                      "\n✓ File restored! Open utils.py to verify the doc comments are gone."
                  )
              else:
                  print("\nKept the modified file.")


      asyncio.run(main())
      ```

      ```typescript try_checkpointing.ts theme={null}
      import { query } from "@anthropic-ai/claude-agent-sdk";
      import * as readline from "readline";

      async function main() {
        // Configure the SDK with checkpointing enabled
        // - enableFileCheckpointing: Track file changes for rewinding
        // - permissionMode: Auto-accept file edits without prompting
        // - extraArgs: Required to receive user message UUIDs in the stream
        const opts = {
          enableFileCheckpointing: true,
          permissionMode: "acceptEdits" as const,
          extraArgs: { "replay-user-messages": null }
        };

        let sessionId: string | undefined; // Store the session ID for resuming
        let checkpointId: string | undefined; // Store the user message UUID for rewinding

        console.log("Running agent to add doc comments to utils.ts...\n");

        // Run the agent and capture checkpoint data from the response stream
        const response = query({
          prompt: "Add doc comments to utils.ts",
          options: opts
        });

        try {
          for await (const message of response) {
            // Capture the first user message UUID - this is our restore point
            if (message.type === "user" && message.uuid && !checkpointId) {
              checkpointId = message.uuid;
            }
            // Capture the session ID so we can resume later
            if ("session_id" in message) {
              sessionId = message.session_id;
            }
          }
        } catch (error) {
          // A single-shot query() throws after yielding an error result. If the
          // failure was an error result, checkpointId and sessionId were already
          // captured by the loop above; connection or process failures yield no
          // result message.
          console.error(`Session ended with an error: ${error}`);
        }

        console.log("Done! Open utils.ts to see the added doc comments.\n");

        // Ask the user if they want to rewind the changes
        if (checkpointId && sessionId) {
          const rl = readline.createInterface({
            input: process.stdin,
            output: process.stdout
          });

          const answer = await new Promise<string>((resolve) => {
            rl.question("Rewind to remove the doc comments? (y/n): ", resolve);
          });
          rl.close();

          if (answer.toLowerCase() === "y") {
            // Resume the session with an empty prompt, then rewind
            const rewindQuery = query({
              prompt: "", // Empty prompt opens the connection
              options: { ...opts, resume: sessionId }
            });

            for await (const msg of rewindQuery) {
              await rewindQuery.rewindFiles(checkpointId); // Restore files
              break;
            }

            console.log("\n✓ File restored! Open utils.ts to verify the doc comments are gone.");
          } else {
            console.log("\nKept the modified file.");
          }
        }
      }

      main();
      ```
    </CodeGroup>
  </Step>

  <Step title="Ejecutar el ejemplo">
    Ejecute el script desde el mismo directorio que su archivo de utilidad.

    <Tip>
      Abra su archivo de utilidad (`utils.py` o `utils.ts`) en su IDE o editor antes de ejecutar el script. Verá que el archivo se actualiza en tiempo real mientras el agente agrega comentarios de documentación, luego revierte al original cuando elige revertir.
    </Tip>

    <Tabs>
      <Tab title="Python">
        ```bash theme={null}
        python try_checkpointing.py
        ```
      </Tab>

      <Tab title="TypeScript">
        ```bash theme={null}
        npx tsx try_checkpointing.ts
        ```
      </Tab>
    </Tabs>

    Verá que el agente agrega comentarios de documentación, luego un mensaje preguntando si desea revertir. Si elige sí, el archivo se restaura a su estado original.
  </Step>
</Steps>

<h2 id="limitations">
  Limitaciones
</h2>

El checkpointing de archivos tiene las siguientes limitaciones:

| Limitación | Descripción |
| - | - |
| Solo herramientas Write/Edit/NotebookEdit | Los cambios realizados a través de comandos Bash no se rastrean |
| Ediciones de subagentes | Las ediciones que aplica un [subagente](/docs/es/agent-sdk/subagents) no se rastrean ni se restauran, excepto una skill con `context: fork` ejecutándose en primer plano; use git para revertir ediciones no rastreadas |
| Misma sesión | Los checkpoints están vinculados a la sesión que los creó |
| Solo contenido de archivo | Crear, mover o eliminar directorios no se deshace al revertir |
| Archivos locales | Los archivos remotos o de red no se rastrean |

<h2 id="troubleshooting">
  Solución de problemas
</h2>

<h3 id="checkpointing-options-not-recognized">
  Las opciones de checkpointing no se reconocen
</h3>

Si `enableFileCheckpointing` o `rewindFiles()` no está disponible, es posible que esté en una versión anterior del SDK.

**Solución**: Actualice a la última versión del SDK:

* **Python**: `pip install --upgrade claude-agent-sdk`
* **TypeScript**: `npm install @anthropic-ai/claude-agent-sdk@latest`

<h3 id="user-messages-don’t-have-uuids">
  Los mensajes de usuario no tienen UUIDs
</h3>

Si `message.uuid` es `undefined` o está faltando, no está recibiendo UUIDs de checkpoint.

**Causa**: La opción `replay-user-messages` no está establecida.

**Solución**: Agregue `extra_args={"replay-user-messages": None}` (Python) o `extraArgs: { 'replay-user-messages': null }` (TypeScript) a sus opciones.

<h3 id="no-file-checkpoint-found-for-this-message-error">
  Error "No file checkpoint found for this message"
</h3>

Este error ocurre cuando los datos de checkpoint no existen para el UUID de mensaje de usuario especificado.

**Causas comunes**:

* El checkpointing de archivos no estaba habilitado en la sesión original (`enable_file_checkpointing` o `enableFileCheckpointing` no estaba establecido en `true`)
* La sesión no se completó correctamente antes de intentar reanudar y revertir

**Solución**: Asegúrese de que `enable_file_checkpointing=True` (Python) o `enableFileCheckpointing: true` (TypeScript) estuviera establecido en la sesión original, luego use el patrón mostrado en los ejemplos: capture el UUID del primer mensaje de usuario, complete la sesión completamente, luego reanude con un mensaje vacío y llame a `rewindFiles()` una sola vez.

<h3 id="file-rewinding-is-not-enabled-error">
  Error "File rewinding is not enabled"
</h3>

Este error ocurre cuando intenta una reversión no interactiva sin checkpointing habilitado: ejecutar `claude -p` simple con `--rewind-files`, o ejecutar una sesión del SDK, incluida una reanudada, cuyas opciones no habilitan checkpointing. El SDK establece la variable de entorno `CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING` internamente solo cuando `enable_file_checkpointing` (Python) o `enableFileCheckpointing` (TypeScript) está habilitado en la sesión que realiza la reversión; la CLI simple nunca la establece.

**Solución**: Para la CLI simple, establezca la variable de entorno al ejecutar el comando:

```bash theme={null}
CLAUDE_CODE_ENABLE_SDK_FILE_CHECKPOINTING=true claude -p --resume <session-id> --rewind-files <checkpoint-uuid>
```

Para el SDK, establezca `enable_file_checkpointing=True` (Python) o `enableFileCheckpointing: true` (TypeScript) en la sesión reanudada, como lo hacen los ejemplos en esta página.

<h3 id="processtransport-is-not-ready-for-writing-error">
  Error "ProcessTransport is not ready for writing"
</h3>

Este error ocurre cuando llama a `rewindFiles()` o `rewind_files()` después de haber terminado de iterar a través de la respuesta. La conexión al proceso de CLI se cierra cuando se completa el bucle.

**Solución**: Reanude la sesión con un mensaje vacío, luego llame a rewind en la nueva consulta. El ejemplo principal bajo [Implement checkpointing](#implement-checkpointing) muestra la llamada de reanudación y reversión en ambos idiomas, en el comentario marcado Paso 3.

<h2 id="next-steps">
  Próximos pasos
</h2>

* **[Sessions](/docs/es/agent-sdk/sessions)**: aprenda cómo reanudar sesiones, que es necesario para revertir después de que se complete el flujo. Cubre IDs de sesión, reanudación de conversaciones y bifurcación de sesiones.
* **[Permissions](/docs/es/agent-sdk/permissions)**: configure qué herramientas puede usar Claude y cómo se aprueban las modificaciones de archivos. Útil si desea más control sobre cuándo ocurren las ediciones.
* **[TypeScript SDK reference](/docs/es/agent-sdk/typescript)**: referencia completa de API incluyendo todas las opciones para `query()` y el método `rewindFiles()`.
* **[Python SDK reference](/docs/es/agent-sdk/python)**: referencia completa de API incluyendo todas las opciones para `ClaudeAgentOptions` y el método `rewind_files()`.