How to Migrate from Claude Fable 5 to Fable 5.1: Breaking Changes, Effort Controls, Progress Updates, and Preserved Thinking

Migration impact in one sentence

Most Claude Fable 5 applications can start the Fable 5.1 migration by changing the model identifier to claude-fable-5-1, but direct Messages API integrations, custom agent harnesses, tool routers, and systems that persist Claude thinking blocks need a real code review because Fable 5.1 changes how tool choice, preserved thinking, and edited conversation history behave.

Anthropic’s Fable 5.1 migration guidance describes the release as mostly compatible with Fable 5, not as a drop-in upgrade for every production stack. The difference matters operationally: a stateless summarization endpoint with no tools and no stored conversation replay may only need a model-name change and regression tests, while an agent that resumes multi-day sessions, calls tools, edits prior turns, or falls back to older Claude models can hit hard failures unless the migration handles the three documented breaking changes.

This tutorial treats the migration as a controlled production change rather than a benchmark exercise. The opening section identifies which teams need code changes, lists the specifications and pricing details that affect migration planning, summarizes the breaking changes, and gives you a preflight inventory to run before touching production traffic. Later sections can use that inventory to update request payloads, preserve thinking safely, add effort controls, and decide whether beta progress updates belong in your agent loop.

Who can make a model-name-only change, and who needs code migration?

A model-name-only change is realistic only when the calling application does not force tool selection, does not store and replay thinking blocks across models, does not edit earlier messages in a conversation before resuming, and does not depend on undocumented request-shaping behavior. In that narrow case, the migration task is still not “skip testing”; it is “change the model ID, run compatibility tests, compare outputs on representative prompts, and verify cost and latency observability still labels the new model correctly.”

Claude Managed Agents are the clearest case for a low-code migration path. Anthropic’s migration notes say Managed Agents generally require only the model-name change. That statement should not be overextended to custom agents, because Managed Agents and direct Messages API integrations place different responsibilities on the developer. If your organization built its own memory layer, tool scheduler, retry policy, cache-boundary logic, or conversation compactor, your application owns the migration behavior even when the model API remains familiar.

Claude Code users should treat the migration as a project-level refactor rather than a single global setting when repositories contain scripts, CI jobs, local configuration, or generated API clients. Anthropic documents the Claude Code command /claude-api migrate this project to claude-fable-5-1, which is useful for surfacing project changes, but teams should still review diffs for tool-choice assumptions, persisted histories, and context-editing behavior before accepting generated edits.

Direct API integrations need a code migration if any request uses tool_choice set to any or to a specific named tool, because Anthropic documents that forced tool choice returns a 400 error on Fable 5.1. The replacement pattern is not to find another way to force the model; it is to use tool_choice: auto and constrain outcomes with strict tool schemas, structured outputs, validation, and retry logic owned by the application.

Stored conversation systems need a code migration if they persist Claude thinking blocks, replay old transcripts into new requests, or allow operators and compaction jobs to edit earlier content. Fable 5.1 introduces preserved-thinking constraints that are easy to violate in a memory service: older Claude models cannot read Fable 5.1 thinking blocks, and changing content before an existing thinking block can invalidate that block. If your application maintains long-lived sessions, you need explicit directionality and append-only rules before rollout.

For a broader enterprise planning baseline, pair this article’s Fable-specific steps with . That guide is the right place to centralize governance questions such as who may approve model changes, which workloads justify frontier reasoning capability, and how business units should document safety, privacy, and retention decisions before moving critical systems. For deeper context on Claude Fable 5 Enterprise Guide, GPT-5.5 vs Claude Fable 5: The Complete Enterprise Benchmark Comparison After Anthropic’s Export Control Shutdown is a practical companion. This article compares GPT-5.5 and Claude Fable 5 for enterprise buyers, covering benchmark performance and the market impact of Anthropic’s export-control shutdown.

Fable 5.1 specifications that affect migration planning

Fable 5.1 uses the model ID claude-fable-5-1, supports a one-million-token context window, and allows up to 128K output tokens according to Anthropic’s model documentation. Those limits are migration-relevant because long-context applications often depend on stable prompt prefixes, cached context, compaction summaries, and replayed state; changing the model without testing those mechanics can hide errors until an unusually long or resumed session reaches production.

Anthropic lists Fable 5.1 at the same base input and output prices as Fable 5: $10 per million input tokens and $50 per million output tokens. The pricing change that matters for many agentic workloads is cache reads, which Anthropic lists at $0.25 per million tokens for Fable 5.1. Five-minute cache writes are listed at $12.50 per million tokens, one-hour cache writes at $20 per million tokens, and Batch API requests receive a 50% input-and-output discount according to the official Fable 5.1 documentation.

Anthropic’s public announcement estimates that Fable 5.1 costs 25% less than Fable 5 for typical token-billed workloads because of lower cache-read pricing, with savings up to approximately 45% for highly agentic work. Treat those as vendor estimates, not guaranteed outcomes for your application. Your realized cost depends on the percentage of tokens served from cache, the number of tool turns, the effort setting used per request or turn, output length, and whether your system invalidates prompt prefixes by editing earlier context.

Always-on adaptive thinking is a functional migration issue, not just a model-quality feature. Because thinking blocks become part of the conversational state that may be preserved, replayed, or invalidated, applications that store transcripts need rules for what may be appended, what may be compacted, and which models may consume which histories. If your fallback path sends a Fable 5.1 transcript to Fable 5, Opus 5, or another older Claude model, you must account for Anthropic’s warning that older models cannot read Fable 5.1 thinking blocks.

The three breaking changes to find before rollout

The first breaking change is forced tool choice. Fable 5.1 returns a 400 error when tool_choice is any or a named tool, so migration work must remove those request patterns before production traffic reaches the new model. A practical replacement is tool_choice: auto with tight JSON schemas, explicit instructions about when a tool is required, server-side validation of the assistant’s response, and application-level retries when the model chooses an invalid path.

The second breaking change is thinking-block directionality. Older Claude models cannot consume Fable 5.1 thinking blocks, which affects fallbacks, reprocessing jobs, stored chat viewers that rehydrate transcripts, and evaluation harnesses that compare multiple models on the same conversation state. The safe decision rule is simple: if a conversation contains Fable 5.1 thinking, route continuation to Fable 5.1-compatible handling or strip/transform state only according to Anthropic-supported patterns; do not blindly replay that transcript into an older model.

The third breaking change is prefix sensitivity around preserved thinking. Anthropic says changing content before an existing thinking block can invalidate it. This is especially important for systems that edit prior turns to redact data, inject policy reminders, rewrite tool outputs, compress old context in place, or reorder messages before replay. For Fable 5.1 migrations, append-only history should be the default, and compaction should create new summaries through a controlled server-side process rather than mutating earlier content in a way that breaks thinking continuity.

Operational warning: do not migrate by changing the model name in a shared router and waiting for errors. Forced tool choice can fail immediately with 400, while thinking-block and prefix-invalidation problems may appear only after resumed sessions, fallback events, or context-compaction jobs run under real traffic.

Preflight inventory before changing production traffic

Before rollout, create a concrete inventory of every place Fable 5 is referenced and every component that stores or modifies conversation state. This is the stage where many teams find hidden coupling: a prompt-testing notebook hardcodes the old model, a Bedrock or Vertex adapter uses a separate model mapping, a replay worker sends archived messages to a fallback model, or a tool router sets tool_choice based on task type.

Use as the cross-team checklist for owners, environments, tests, rollback conditions, and sign-off evidence. The Fable 5.1-specific inventory above should become a set of tickets with named owners: one for forced tool choice, one for thinking-block directionality, one for append-only history, one for platform adapters, one for cost telemetry, and one for evaluation coverage. For deeper context on Claude API Migration Checklist, The Complete GPT-4.5 to GPT-5.5 Migration Checklist: What Changed, What Broke, and How to Update Your Prompts is a practical companion. This article provides a complete migration checklist for moving from GPT-4.5 to GPT-5.5, focusing on what changed, what broke, and how teams should update prompts and evaluation workflows.

How to treat new effort and progress features during the opening migration

Fable 5.1 adds beta capabilities that can improve long-running agent workflows, but they should not be mixed into the first production cut unless you can isolate and test them. Anthropic documents beta per-message effort with the mid-conversation-output-config-2026-07-01 beta header, beta turn-scoped system messages using clear_at: next_user_message with the mid-conversation-system-clear-at-2026-08-21 beta header, and beta user-visible progress updates using thinking.display: updates with the thinking-display-updates-2026-08-18 beta header.

The practical sequencing rule is to separate compatibility migration from optimization. First, remove unsupported forced-tool requests, preserve valid histories, and confirm the model ID change works across every platform path. Then run effort-level evaluations, cache-read cost analysis, and progress-update user experience tests. That sequencing prevents a failed beta feature experiment from being misdiagnosed as a core Fable 5.1 compatibility problem.

A safe migration plan therefore starts with an inventory, continues with code changes for the three breaking changes, and only then adds optional controls such as per-message effort or user-visible progress updates. That order gives developers a clean rollback boundary: if the base migration fails, revert the model and compatibility edits; if a later effort or progress experiment fails, disable that feature without undoing the core Fable 5.1 migration.

Code-level breaking changes: model IDs, tool choice, thinking blocks, and append-only history

Anthropic’s migration guide characterizes Fable 5 to Fable 5.1 as mostly compatible, but the operational risk is concentrated in three places: requests that force tool use, histories that contain preserved Fable 5.1 thinking blocks, and middleware that rewrites prior conversation content. Treat these as hard compatibility checks rather than cleanup tasks, because Anthropic documents that forced tool choice can return a 400 error, older Claude models cannot read Fable 5.1 thinking blocks, and edits before an existing thinking block can invalidate that block.

The safest migration pattern is to split your rollout into two changes. First, change only the model identifier and run your existing regression suite. Second, enable any Fable 5.1-specific controls, such as per-message effort or progress updates, after the base migration is stable. This sequencing keeps a forced-tool error, a thinking-prefix mismatch, or an unsupported thinking configuration from being misdiagnosed as a general model-quality regression.

Migration matrix for direct API integrations

Before and after: isolate the model-ID change

Start with a single source of truth for the model ID. If your Fable 5 integration currently hard-codes a model name in multiple services, change that architecture before you change production traffic. A centralized setting lets you canary Fable 5.1 by tenant, environment, or workload without deploying a different binary for every rollback decision.

Before: Python with the model value embedded or spread through the codebase.

from anthropic import Anthropic

client = Anthropic()

# Existing Fable 5 configuration in your application.
# Keep your exact current value in the migration inventory.
CURRENT_FABLE_5_MODEL_ID = "${CURRENT_FABLE_5_MODEL_ID}"

message = client.messages.create(
    model=CURRENT_FABLE_5_MODEL_ID,
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Review this patch and identify correctness risks."
        }
    ],
)

After: Python with the Fable 5.1 model ID in configuration.

import os
from anthropic import Anthropic

client = Anthropic()

MODEL_ID = os.environ.get("ANTHROPIC_MODEL", "claude-fable-5-1")

message = client.messages.create(
    model=MODEL_ID,
    max_tokens=2048,
    messages=[
        {
            "role": "user",
            "content": "Review this patch and identify correctness risks."
        }
    ],
)

# Operational check: emit the resolved model ID in structured logs.
print({"event": "claude_request_created", "model": MODEL_ID})

The same rule applies to raw JSON request builders. Do not change model ID, tool policy, transcript compaction, and effort settings in the same commit unless your release process can bisect request-level failures. A model-only change gives you a clean baseline for latency, cost, tool-routing, and refusal-rate comparisons under your own workload.

Before: JSON request body using the current Fable 5 setting.

{
  "model": "${CURRENT_FABLE_5_MODEL_ID}",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "user",
      "content": "Review this patch and identify correctness risks."
    }
  ]
}

After: JSON request body using Fable 5.1.

{
  "model": "claude-fable-5-1",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "user",
      "content": "Review this patch and identify correctness risks."
    }
  ]
}

Breaking change 1: replace forced tool choice with auto, strict schema, and explicit instructions

Anthropic’s Fable 5.1 migration guidance says forced tool choice with any or a named tool is not supported and can return a 400 error. This affects agent harnesses that previously used forced selection to guarantee a database lookup, policy check, file edit, or external API call. The migration target is not “remove tools”; it is “let the model choose automatically, but make the desired tool path unambiguous.”

Before: Python that forces a named tool.

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=1024,
    tools=[
        {
            "name": "lookup_order",
            "description": "Look up an order by order_id.",
            "input_schema": {
                "type": "object",
                "properties": {
                    "order_id": {"type": "string"}
                },
                "required": ["order_id"]
            }
        }
    ],
    tool_choice={"type": "tool", "name": "lookup_order"},
    messages=[
        {
            "role": "user",
            "content": "Where is order A12345?"
        }
    ],
)

After: Python using auto, a stricter schema, and an explicit instruction.

response = client.messages.create(
    model="claude-fable-5-1",
    max_tokens=1024,
    tools=[
        {
            "name": "lookup_order",
            "description": "Look up a customer order by its exact order_id.",
            "input_schema": {
                "type": "object",
                "additionalProperties": False,
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "The exact order identifier supplied by the user."
                    }
                },
                "required": ["order_id"]
            }
        }
    ],
    tool_choice={"type": "auto"},
    messages=[
        {
            "role": "user",
            "content": (
                "If the user asks about a specific order and provides an order ID, "
                "call lookup_order before answering. User request: Where is order A12345?"
            )
        }
    ],
)

The strict schema prevents silent argument drift, while the user-facing instruction gives the model a clear routing rule. If your application requires machine-checked JSON after the tool result, keep that requirement separate from forced tool selection and validate it in your own runtime. Teams that need stricter response contracts should pair this migration with a structured-output review rather than relying on forced tool choice as a control surface. For deeper context on Structured Outputs for Reliable JSON, How to Use ChatGPT Structured Outputs for Reliable JSON: Complete API Tutorial with Schema Validation and Error Handling is a practical companion. This article explains how to use ChatGPT structured outputs for reliable JSON, including schema validation and error-handling patterns for production API applications.

Before: JSON request body with unsupported forced any selection.

{
  "model": "claude-fable-5-1",
  "max_tokens": 1024,
  "tool_choice": { "type": "any" },
  "tools": [
    {
      "name": "lookup_order",
      "description": "Look up an order by order_id.",
      "input_schema": {
        "type": "object",
        "properties": {
          "order_id": { "type": "string" }
        },
        "required": ["order_id"]
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Where is order A12345?"
    }
  ]
}

After: JSON request body with automatic tool choice and a narrow schema.

{
  "model": "claude-fable-5-1",
  "max_tokens": 1024,
  "tool_choice": { "type": "auto" },
  "tools": [
    {
      "name": "lookup_order",
      "description": "Look up a customer order by its exact order_id.",
      "input_schema": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "order_id": {
            "type": "string",
            "description": "The exact order identifier supplied by the user."
          }
        },
        "required": ["order_id"]
      }
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "If the user asks about a specific order and provides an order ID, call lookup_order before answering. User request: Where is order A12345?"
    }
  ]
}

Operational warning: do not simulate forced tool choice by rejecting every non-tool response and blindly retrying the same prompt. That pattern can create duplicate external actions when a previous call succeeded but your harness lost state. Instead, make tool idempotency explicit, record tool-call attempts, and retry only from a known safe checkpoint.

Breaking change 2: handle unsupported thinking configurations instead of trying to disable thinking

Fable 5.1 uses always-on adaptive thinking, and Anthropic documents new effort-related controls separately from the base migration. Audit wrappers that were built around older assumptions such as “disable thinking for cheap requests,” “strip internal thinking blocks before storing history,” or “reconstruct preserved thinking from a summarized transcript.” Those assumptions are dangerous in Fable 5.1 because reasoning state may be part of the preserved conversation structure that the next turn expects to see unchanged.

Before: Python wrapper carrying a legacy thinking override and mutating stored content.

def send_request(user_text, stored_messages):
    # Problematic migration pattern:
    # - assumes thinking can be disabled by wrapper policy
    # - strips non-text assistant content before the next turn
    stripped_messages = [
        {
            "role": m["role"],
            "content": only_user_visible_text(m["content"])
        }
        for m in stored_messages
    ]

    return client.messages.create(
        model="claude-fable-5-1",
        max_tokens=2048,
        thinking={"enabled": False},
        messages=stripped_messages + [
            {"role": "user", "content": user_text}
        ],
    )

After: Python wrapper that removes unsupported assumptions and preserves prior content.

def send_request(user_text, stored_messages):
    # Fable 5.1 uses always-on adaptive thinking.
    # Preserve stored messages exactly as returned unless you are performing
    # a controlled compaction step that replaces the whole prior segment.
    messages = stored_messages + [
        {"role": "user", "content": user_text}
    ]

    return client.messages.create(
        model="claude-fable-5-1",
        max_tokens=2048,
        messages=messages,
    )

The JSON version of the same migration is deliberately simple: remove undocumented or legacy thinking toggles from the base request. If you later test documented beta effort controls, isolate that experiment behind its required beta header and do not mix it with the first production model-ID rollout.

Before: JSON with a legacy thinking assumption.

{
  "model": "claude-fable-5-1",
  "max_tokens": 2048,
  "thinking": {
    "enabled": false
  },
  "messages": [
    {
      "role": "user",
      "content": "Summarize the risk in this incident report."
    }
  ]
}

After: JSON that lets Fable 5.1 use its default adaptive thinking behavior.

{
  "model": "claude-fable-5-1",
  "max_tokens": 2048,
  "messages": [
    {
      "role": "user",
      "content": "Summarize the risk in this incident report."
    }
  ]
}

For diagnostics, Anthropic references the thinking-binding-controls-2026-08-01 beta header in the migration context. Treat that as a diagnostic aid, not a general permission to rewrite historical reasoning state. The production rule remains simpler: preserve the transcript exactly, append new turns, and compact only at boundaries your application owns and tests.

Breaking change 3: one-way thinking-block compatibility and prefix-mismatch errors

The thinking-block compatibility rule is one-way. A Fable 5.1 conversation that contains Fable 5.1 thinking blocks should continue on Fable 5.1; older Claude models cannot consume those blocks. This matters for fallback routers because a model downgrade after a partial incident, high latency event, quota failure, or customer-tier switch can break only the conversations that have already passed through Fable 5.1.

A safe fallback does not pass raw Fable 5.1 thinking-block history to an older model. Instead, it either keeps the session pinned to Fable 5.1 or creates a user-visible compaction summary that omits preserved thinking blocks and restates the facts, decisions, open tasks, tool results, and constraints needed for a new model turn. That compaction summary is a new conversation artifact, not a mutation of the original preserved transcript.

Prefix-mismatch errors are the other side of the same preservation rule. Anthropic documents that changing content before an existing thinking block can invalidate it. In practice, this means a middleware step that redacts a previous user message, normalizes whitespace, removes an assistant text segment, sorts content blocks, or injects a retroactive system note before a preserved thinking block can make the stored prefix no longer match what the model expects.

Before: Python that edits prior history in place before resuming.

def redact_and_continue(stored_messages, new_user_text):
    # Problem: this mutates earlier content before preserved assistant state.
    for message in stored_messages:
        if message["role"] == "user":
            message["content"] = message["content"].replace("[email protected]", "[redacted]")

    stored_messages.append({
        "role": "user",
        "content": new_user_text
    })

    return client.messages.create(
        model="claude-fable-5-1",
        max_tokens=4096,
        messages=stored_messages,
    )

After: Python that keeps the existing prefix unchanged and appends a correction.

def append_correction_and_continue(stored_messages, new_user_text):
    # Do not edit the serialized prefix that may bind existing thinking blocks.
    messages = stored_messages + [
        {
            "role": "user",
            "content": (
                "Correction for future turns: treat [email protected] as redacted "
                "and do not repeat it. Continue using the prior analysis, but apply "
                "this privacy constraint going forward."
            )
        },
        {
            "role": "user",
            "content": new_user_text
        }
    ]

    return client.messages.create(
        model="claude-fable-5-1",
        max_tokens=4096,
        messages=messages,
    )

Before: JSON transcript where a previous user turn has been rewritten.

{
  "model": "claude-fable-5-1",
  "max_tokens": 4096,
  "messages": [
    {
      "role": "user",
      "content": "My email is [redacted]. Analyze the account issue."
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "I will inspect the account timeline and identify likely causes."
        },
        {
          "type": "thinking",
          "thinking": "PRESERVED_THINKING_BLOCK_FROM_PREVIOUS_FABLE_5_1_TURN"
        }
      ]
    },
    {
      "role": "user",
      "content": "Continue the analysis."
    }
  ]
}

After: JSON transcript that preserves history and appends the new constraint.

{
  "model": "claude-fable-5-1",
  "max_tokens": 4096,
  "messages": [
    {
      "role": "user",
      "content": "My email is [email protected]. Analyze the account issue."
    },
    {
      "role": "assistant",
      "content": [
        {
          "type": "text",
          "text": "I will inspect the account timeline and identify likely causes."
        },
        {
          "type": "thinking",
          "thinking": "PRESERVED_THINKING_BLOCK_FROM_PREVIOUS_FABLE_5_1_TURN"
        }
      ]
    },
    {
      "role": "user",
      "content": "Correction for future turns: treat [email protected] as redacted and do not repeat it."
    },
    {
      "role": "user",
      "content": "Continue the analysis."
    }
  ]
}

If your privacy, retention, or safety policy requires removing earlier content, do not perform invisible in-place edits and then continue as if the same preserved reasoning state remains valid. End that preserved segment, create a compacted replacement transcript that contains only allowed information, and accept that the next request is starting from the compacted state rather than from the original bound prefix.

Append-only history is the default migration discipline

Append-only history is not just a logging preference; it is the easiest way to avoid invalidating Fable 5.1’s preserved thinking. The application should treat every previously sent message as immutable once an assistant response containing preserved state has been stored. New facts, corrections, policy changes, and scope reductions should be expressed as new user or system-level instructions in a later turn, not as edits to earlier messages.

Use a compaction boundary when append-only history becomes too large or contains information that can no longer be retained. A compaction step should produce a fresh summary with critical constraints, tool results, unresolved questions, and user-approved decisions. After compaction, persist the summary as the new starting point and do not mix it with stale preserved thinking blocks from the pre-compaction segment.

The practical release gate is straightforward: replay representative Fable 5 conversations through Fable 5.1 with forced tool choice removed, verify that no middleware rewrites prior turns, simulate downgrade after a Fable 5.1 response, and confirm your fallback path does not send Fable 5.1 thinking blocks to older models. Only after those checks pass should you evaluate beta effort controls, turn-scoped system messages, or user-visible progress updates on top of the migrated baseline.

Add Fable 5.1’s new controls without breaking cache or conversation state

Fable 5.1 adds three migration-relevant controls that are useful only if you treat them as turn controls, not as permission to rewrite old conversation state. Anthropic documents beta support for per-message effort, turn-scoped system messages, and user-visible progress updates between tool calls. In a direct Messages API integration, these controls should be added at the newest request boundary while preserving the existing cached prefix, prior thinking blocks, prior tool results, and prior user messages exactly as they were stored.

The practical rule is simple: change the configuration for the next assistant message, not the historical transcript. If you need a cheaper pass over a routine follow-up, lower effort for that next generated message. If you need temporary steering for one user turn, add a system block that clears at the next user message. If you need the user to see that a long-running agent is still working, request progress updates through the thinking display option. None of these require editing content before an existing Fable 5.1 thinking block, which Anthropic flags as a way to invalidate preserved thinking.

Enable the beta controls explicitly and narrowly

Use the documented beta header values only for the features you are actually exercising. A migration rollout should not turn on every beta flag globally if only one route needs progress updates, because narrower activation makes failures easier to diagnose and rollback. The three documented beta values for this section are:

• mid-conversation-output-config-2026-07-01 for changing output configuration such as effort during a conversation.
• mid-conversation-system-clear-at-2026-08-21 for turn-scoped system messages using clear_at: next_user_message.
• thinking-display-updates-2026-08-18 for user-visible progress updates using thinking.display: updates.

Implementation recommendation: put these beta values behind a route-level or workflow-level feature flag. For example, a code-review agent may need per-message effort and progress updates, while a short classification endpoint may need neither. This keeps your compatibility surface smaller and prevents a successful Fable 5.1 model-name migration from becoming entangled with unrelated beta-control changes.

{
  "headers": {
    "anthropic-beta": "mid-conversation-output-config-2026-07-01,mid-conversation-system-clear-at-2026-08-21,thinking-display-updates-2026-08-18"
  },
  "body": {
    "model": "claude-fable-5-1",
    "max_tokens": 12000,
    "thinking": {
      "effort": "medium",
      "display": "updates"
    },
    "system": [
      {
        "type": "text",
        "text": "For this turn only, summarize progress for the user before each expensive or multi-step tool phase.",
        "clear_at": "next_user_message"
      }
    ],
    "messages": [
      {
        "role": "user",
        "content": "Audit the migration branch, identify risky Fable 5.1 incompatibilities, and propose minimal patches."
      }
    ],
    "tool_choice": {
      "type": "auto"
    }
  }
}

Operational warning: keep tool_choice on auto when migrating Fable 5 workloads. Anthropic’s migration guide identifies forced tool choice with any or a named tool as a breaking change that returns a 400 error on Fable 5.1. If your previous integration relied on forced tool selection, replace that behavior with strict schemas, clear tool descriptions, and explicit instructions about when each tool should be used.

Use per-message effort as a routing decision, not a global default

Anthropic documents that Fable 5.1 has always-on adaptive thinking and a high default API effort. The new beta output-configuration control lets a client vary effort during a conversation without treating the effort change as a reason to rewrite the prefix. In practice, this means the same long-running session can use lower effort for a routine file lookup, higher effort for a multi-file architectural decision, and then lower effort again for a narrow formatting pass.

Decision rule: set effort according to the risk and ambiguity of the next assistant message. Use lower effort for deterministic retrieval, small refactors, schema-constrained extraction, or “find where this symbol is defined” work. Use medium or high effort for code migration planning, tool-result synthesis, and tasks where the model must reconcile several pieces of evidence. Reserve xhigh or max effort for the small number of turns where the extra reasoning budget is operationally justified, and leave additional output room at those levels as Anthropic’s prompting guidance recommends.

{
  "model": "claude-fable-5-1",
  "max_tokens": 4000,
  "thinking": {
    "effort": "low"
  },
  "messages": [
    {
      "role": "user",
      "content": "Find all places where the integration sends tool_choice.type as any or a named tool. Return file paths and line references only."
    }
  ],
  "tool_choice": {
    "type": "auto"
  }
}

{
  "model": "claude-fable-5-1",
  "max_tokens": 20000,
  "thinking": {
    "effort": "high"
  },
  "messages": [
    {
      "role": "user",
      "content": "Using the search results already appended to this conversation, design the minimal migration patch and explain any behavior changes that require human review."
    }
  ],
  "tool_choice": {
    "type": "auto"
  }
}

The cache-preserving part is the important engineering detail. If your application has a stable prefix containing policies, tool definitions, repository context, prior messages, and Fable 5.1 thinking blocks, do not mutate that prefix to change effort. Send the next request with the desired effort setting and the beta value mid-conversation-output-config-2026-07-01. Your cache-hit behavior still depends on your exact prompt-caching layout and unchanged prefix boundaries, but an effort change should be modeled as a new-turn configuration change rather than a historical transcript edit. For teams optimizing large cached prefixes, pair this migration with the budgeting guidance in . For deeper context on Long Context Cost Management, GPT-6 Astra Prompt Caching Guide: Explicit Breakpoints, Cache Keys, 30-Minute TTL, and Long-Context Cost Control is a practical companion. This article covers GPT-6 Astra prompt caching, explicit breakpoints, cache keys, TTL behavior, and cost-control strategies for long-context applications.

Add turn-scoped system instructions with clear_at

Turn-scoped system messages solve a common agent problem: the user asks for a temporary behavior, such as “be extra conservative on this deployment review,” and the old integration either pollutes the permanent system prompt or injects a user message that remains ambiguous later. Fable 5.1’s documented beta control supports a system block with clear_at: next_user_message, activated with mid-conversation-system-clear-at-2026-08-21. The instruction applies to the current turn and is cleared when the next user message arrives.

{
  "model": "claude-fable-5-1",
  "thinking": {
    "effort": "medium"
  },
  "system": [
    {
      "type": "text",
      "text": "For this turn only, do not propose broad rewrites. Limit recommendations to changes required for Fable 5.1 compatibility.",
      "clear_at": "next_user_message"
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Review the migration diff and identify only blocking issues."
    }
  ]
}

Recommended usage: use clear_at for temporary scope, verbosity, review posture, progress-update expectations, or workflow phase instructions. Do not use it for durable governance requirements, data-handling constraints, tool permissions, or safety policies that must remain active across the entire session. Durable controls belong in your permanent system configuration, authorization layer, tool server, or application policy engine.

Turn-scoped instructions are also useful during human checkpoints. For example, after an agent proposes a database migration, a reviewer can approve only the analysis phase and add a one-turn instruction that the model must not generate executable deployment commands. That instruction should clear before the next user turn so the session does not accidentally carry a review-only constraint into a later planning phase.

Expose progress updates without pretending the model runs your infrastructure

Fable 5.1 can provide user-visible progress updates between tool calls when the request uses thinking.display: updates with the beta value thinking-display-updates-2026-08-18. Treat this as a user-experience and observability feature for long-running model/tool loops. Your application still owns job state, persistence, retries, permissions, cancellation, audit logging, and final action approval.

{
  "model": "claude-fable-5-1",
  "max_tokens": 18000,
  "thinking": {
    "effort": "high",
    "display": "updates"
  },
  "system": [
    {
      "type": "text",
      "text": "When work requires multiple tool phases, provide concise user-facing progress updates between phases. Do not expose secrets, hidden chain-of-thought, or raw credentials.",
      "clear_at": "next_user_message"
    }
  ],
  "messages": [
    {
      "role": "user",
      "content": "Inspect the repository, update the Fable 5.1 integration, run the migration tests, and report any remaining manual steps."
    }
  ],
  "tool_choice": {
    "type": "auto"
  }
}

Product rule: progress updates should describe observable work, not hidden reasoning. Good updates say, “I found three call sites that still use forced tool choice and I’m checking the test harness now.” Bad updates reveal private deliberation, speculate about unsupported system behavior, or imply that the model has completed external work before your tool layer confirms it. For application patterns that surface these messages in agent UIs, see . For deeper context on AI Agent Progress Updates, Enterprise AI Agent Orchestration — From Pilot to Production is a practical companion. This enterprise orchestration guide explains the operational controls needed to move AI agents from pilots into observable production workflows, including ownership, monitoring, and staged rollout.

Batch independent tools before raising effort

Anthropic’s prompting guidance for Fable 5.1 recommends batching independent tool calls. This matters because long-running migrations often waste turns by serializing read-only operations that have no dependency on each other. If the agent needs to inspect package files, search for forced tool choice, and list tests, those can be requested as independent tool calls in one phase. The model can then synthesize the combined results in a later message at an appropriate effort level.

{
  "role": "user",
  "content": "First gather evidence. When tool calls are independent, issue them in the same tool phase: search for forced tool_choice usage, search for thinking-block persistence code, list prompt-cache configuration, and list migration tests. Do not patch files until after you summarize findings."
}

Decision rule: batch read-only discovery tools when the outputs do not depend on each other, but keep write tools gated behind a review step or a separate phase. A file edit, migration execution, deployment, account change, or destructive operation is not merely another independent tool call. Your agent harness should enforce permissions regardless of the model’s progress updates or effort setting.

Use server-side compaction when the session’s useful state is smaller than its transcript

Fable 5.1’s one-million-token context window makes very long sessions possible, but it does not remove the need for state management. Anthropic recommends append-only histories, server-side compaction or context editing, and preserving critical constraints in compaction summaries. Use server-side compaction when the conversation has accumulated large tool outputs, repeated logs, or obsolete branches of investigation, but the active task only needs a verified summary, open decisions, file paths, constraints, and unresolved risks.

Use compaction when: the session is approaching your internal context budget; cache reads are no longer economical because the prefix is too large for the remaining work; tool outputs dominate the transcript; or a human-approved summary can preserve the state needed for the next phase. Avoid compaction when exact raw evidence is still needed for correctness, when a compliance review requires the full transcript in-context, or when your summary would omit unresolved safety, security, or permission constraints.

A good compaction summary is not a vague recap. It should preserve the user goal, durable system constraints, approved and rejected actions, current repository or environment identifiers, tool results that matter, exact files changed, tests run, failures observed, and the next safe action. If the agent has been using turn-scoped system messages, the summary should distinguish durable constraints from expired one-turn instructions so that clear_at behavior is not accidentally converted into a permanent rule.

Long-session state diagram in prose

Think of a Fable 5.1 long session as a sequence of state transitions. The first state is the stable prefix: permanent system instructions, tool definitions, durable policy, cached repository or project context, and prior conversation content that must not be edited. The second state is the current user turn: the user’s latest request, optional temporary system blocks with clear_at: next_user_message, and the chosen effort for the next assistant message. The third state is the model planning and tool-selection phase, where progress updates may be displayed if thinking.display: updates is enabled. The fourth state is the tool phase, where independent read-only tools should be batched and write tools should remain permission-gated. The fifth state is result assimilation, where tool results are appended to the transcript rather than spliced into older content. The sixth state is the continuation decision: continue with a new effort level, ask for human review, compact server-side, or end the task with a final answer. When the next user message arrives, any system block marked clear_at: next_user_message falls out of scope, but durable system policy and append-only history remain.

Migration test cases for the new controls

Test 1: effort changes do not mutate prior history. Start a session with a cached prefix and at least one Fable 5.1 assistant response. Send a low-effort lookup turn, then a high-effort synthesis turn, using mid-conversation-output-config-2026-07-01. The expected result is that the client appends new messages only, preserves prior thinking blocks, and does not rewrite content before those blocks. Any middleware that rebuilds old messages to “normalize” effort should fail the test.

Test 2: turn-scoped system instructions expire. Send a request with a system block containing clear_at: next_user_message and the beta value mid-conversation-system-clear-at-2026-08-21. Ask for a narrow compatibility-only review. On the next user turn, ask for a broader design review without re-sending that temporary system block. The expected result is that the narrow instruction does not persist unless your application deliberately sends it again.

Test 3: progress updates are visible but non-sensitive. Enable thinking.display: updates with thinking-display-updates-2026-08-18 for a multi-tool workflow. Confirm that the UI can display concise status between tool phases and that logs do not expose secrets, credentials, hidden reasoning, or unverified claims about external execution. The final answer should remain distinguishable from interim progress messages.

Test 4: independent read tools are batched. Give the model four independent discovery tasks and inspect whether the agent issues them in one tool phase where supported by your harness. The expected result is fewer serial read phases without bypassing write approvals. If the model tries to patch files during discovery, tighten the system or user instruction and enforce write permissions outside the model.

Test 5: compaction preserves operational constraints. Run a long migration session until large tool outputs dominate the transcript, then invoke your server-side compaction path. The summary must include the original migration objective, durable policy, expired one-turn instructions marked as expired, files inspected, files changed, tests run, open failures, and required human approvals. The expected result is a shorter working context that remains safe and actionable without editing old Fable 5.1 thinking blocks.

Rollout recommendation: ship these controls in stages after the base Fable 5.1 compatibility migration passes. First validate model ID, forced-tool-choice removal, and append-only thinking-block handling. Then add per-message effort for selected routes. Next add turn-scoped instructions where product behavior benefits from temporary steering. Finally enable progress updates for long-running workflows whose UI and audit logs are ready to separate interim status from final answers.

Roll out Fable 5.1 as a controlled production change, not a silent model swap

After the compatibility work is complete, treat Fable 5.1 deployment like any other high-impact platform migration: isolate the model-ID change, introduce beta controls only behind feature flags, compare behavior against Fable 5 with production-shaped traffic, and maintain a rollback path that does not replay incompatible thinking blocks into older models. Anthropic describes Fable 5.1 as mostly compatible with Fable 5, but the forced-tool-choice rejection, one-way thinking-block compatibility, and prefix-sensitivity of preserved thinking are enough to justify a staged rollout.

Recommended rollout sequence: begin with offline replay tests, move to shadow traffic, then route a small percentage of live eligible requests, and expand only when cost, latency, refusal, tool-call, and user-visible quality metrics remain inside your acceptance bands. Do not enable per-message effort, turn-scoped system messages, or progress updates for all users during the first cutover unless your harness already records the beta headers, request shape, and downstream UI handling needed to debug those features.

Build shadow testing around compatibility, not only answer quality

Shadow testing should send the same user-visible request and the same available tools to Fable 5.1, but it must not execute side-effecting tool calls such as purchases, deployments, ticket updates, data deletion, or customer notifications. For tool-heavy systems, configure the shadow harness to record intended tool calls, arguments, JSON-schema validation results, and whether calls would have been independent enough to batch, then compare those records with the Fable 5 production path.

Include a dedicated shadow bucket for long conversations because preserved thinking and append-only history issues often appear after several turns rather than in a single prompt. The replay corpus should contain conversations with previous tool results, compacted summaries, system constraints, user corrections, and boundary cases where your current system edits or removes earlier messages. Any workflow that mutates content before an existing thinking block should be flagged for redesign, because Anthropic’s migration guidance warns that changing content before a thinking block can invalidate it.

Use deterministic validators wherever possible. Instead of asking reviewers whether the new answer “looks better,” check whether JSON validates, required citations are present, a tool was called only when permitted, a compacted constraint was preserved, and the final answer stayed within your product’s allowed scope. Human review remains necessary for open-ended reasoning and refusal quality, but automated assertions will find most migration-breaking defects earlier and cheaper.

{
  "shadow_test_record": {
    "request_id": "req_2026_09_06_001",
    "baseline_model": "claude-fable-5",
    "candidate_model": "claude-fable-5-1",
    "executed_candidate_tools": false,
    "candidate_tool_calls_validated_only": true,
    "checks": {
      "no_forced_tool_choice": true,
      "json_schema_valid": true,
      "append_only_history": true,
      "older_model_fallback_excluded_thinking_blocks": true,
      "progress_updates_renderable_if_enabled": true
    }
  }
}

Run compatibility tests that mirror the three breaking changes

Your compatibility suite should contain explicit negative tests for forced tool choice. Any request using tool_choice: any or a named tool should be expected to fail with Fable 5.1, because Anthropic’s migration guide states that forced tool choice returns a 400 error. The passing path should use tool_choice: auto, strict tool schemas or structured outputs, and prompt instructions that tell the model when a tool is required without relying on a now-invalid API control.

Add a one-way thinking-block test before enabling fallback. A conversation containing Fable 5.1 thinking blocks must not be sent to older Claude models, because Anthropic documents that older models cannot read Fable 5.1 thinking blocks. If your incident handler falls back to Fable 5 after a Fable 5.1 error, the fallback layer must either restart from a safe compacted summary without incompatible thinking blocks or route to a compatible Fable 5.1 configuration instead of replaying the raw transcript.

Test prefix integrity by replaying a conversation, then deliberately editing a message before a thinking block and confirming that diagnostics catch the invalid state. During diagnostics, Anthropic documents the thinking-binding-controls-2026-08-01 beta header for investigating preserved-thinking prefix issues. Use that diagnostic path narrowly; do not leave debugging headers enabled globally unless your Anthropic agreement and internal change-control process explicitly approve that configuration.

Track cost by effort level, cache behavior, and output length

Cost tracking should be implemented before canary traffic, because Fable 5.1’s economics depend on request shape. Anthropic’s official Fable 5.1 documentation lists base pricing of $10 per million input tokens and $50 per million output tokens, five-minute cache writes at $12.50 per million tokens, one-hour cache writes at $20 per million tokens, cache reads at $0.25 per million tokens, and a 50% input-and-output discount for Batch API requests. Those figures should be recorded as vendor list prices in your model-cost table rather than buried in application code.

Record input tokens, output tokens, cache-write tokens, cache-read tokens, selected effort, beta headers, model ID, and whether the request was online or batch. This breakdown is more useful than a single “cost per request” number because Fable 5.1’s lower cache-read price can make stable-prefix agent loops cheaper while high-effort long outputs can still drive total spend upward. If you adopt per-message effort with the mid-conversation-output-config-2026-07-01 beta header, report spend by effort level so product owners can see which tasks genuinely require higher reasoning effort.

Decision rule: promote a workload only when its unit economics are stable under production-shaped traffic, not just under a hand-picked benchmark set. For example, a code-review assistant that reads the same repository context repeatedly may benefit from prompt caching, while a one-shot drafting task with long final answers may be dominated by output tokens. Your acceptance report should show both median and high-percentile token use, because long-running agents frequently fail budgets through rare but expensive turns.

Handle refusals, policy differences, and fallback paths deliberately

Refusal handling should distinguish a correct safety refusal from a migration regression. Anthropic states that Fable 5.1 has updated safeguards and that Fable 5.1 may discover vulnerabilities but not develop exploits; therefore, cybersecurity workflows should be evaluated with task labels that separate benign analysis, vulnerability discovery, exploit construction, credential abuse, and operational misuse. A higher refusal rate is not automatically wrong if your baseline allowed requests that should have been blocked, and a lower refusal rate is not automatically safe if it admits disallowed operational steps.

Define fallback behavior by failure class. For syntactic failures such as JSON validation errors, retry once with the same model and a narrower repair prompt. For tool unavailability, ask the user to retry later or switch to a non-tool answer if that is safe. For policy refusals, do not automatically fall back to an older model in an attempt to obtain the prohibited answer. For Fable 5.1-specific transcript incompatibility, restart from a compacted, policy-safe summary that omits Fable 5.1 thinking blocks before routing anywhere else.

Claude Code users can optionally ask Claude Code to help perform the migration with /claude-api migrate this project to claude-fable-5-1. Treat this as an assisted code-change workflow inside Claude Code, not as a substitute for your own review, tests, staging environment, or production approval. Teams that operate Claude Code at scale should pair the assisted migration with repository checks, protected branches, and human approval gates; see for broader operational patterns. For deeper context on Claude Code Production Workflows, 15 writing Prompts for Claude Code u2014 Copy-Paste Ready for Production Workflows is a practical companion. This article offers 15 copy-paste-ready Claude Code prompts for refactoring, debugging, code review, and other production development workflows.

Confirm retention, ZDR eligibility, and audit requirements before launch

Before enabling preserved thinking in regulated or privacy-sensitive systems, confirm your Anthropic retention posture in writing with your organization’s account, legal, and security owners. The Fable 5.1 migration material refers to 30-day retention requirements for preserved-thinking behavior, while Anthropic also describes authorized zero data retention exceptions for eligible customers. Do not assume that every organization, workspace, project, or workload has access to ZDR, and do not represent ZDR as a universal default in your internal architecture documents.

Your launch checklist should state whether requests containing thinking blocks are retained, whether an authorized ZDR exception applies, who approved that exception, and which workloads are excluded because they cannot meet the retention requirement. If your company has contractual limits on storage of customer prompts, source code, secrets, regulated data, or security findings, block production rollout until those limits are reconciled with Anthropic’s documented requirements and your own data-classification policy.

Operational warning: retention posture is not only a vendor setting. Your own logs, traces, prompt archives, evaluation datasets, support exports, and replay queues may retain the same content longer than the model provider. A Fable 5.1 migration should therefore include internal log-redaction and retention review, not only a check of Anthropic account configuration.

Instrument observability for model behavior, not just infrastructure uptime

At minimum, log the model ID, request route, effort setting, beta headers used, token counts, cache read/write counts, tool-call names, tool validation failures, refusal category, retry count, fallback target, and user-visible error state. If progress updates are enabled with thinking.display: updates and the thinking-display-updates-2026-08-18 beta header, record whether the UI received, rendered, suppressed, or dropped each update so support teams can debug “the agent is stuck” reports.

Build dashboards around migration-specific indicators. A sudden rise in 400 errors likely points to missed forced-tool-choice calls or malformed beta feature requests. A rise in fallback volume may indicate schema incompatibility or policy mismatch. A drop in cache reads may indicate that the application is editing the stable prompt prefix or compacting too aggressively. A rise in output tokens at xhigh or max effort may indicate that the prompt does not leave enough output room or asks for unnecessary chain-of-work summaries.

Every alert should include a runbook action. For example, a forced-tool-choice alert should link to the code owners for tool dispatch, the failing request sample, and the approved replacement pattern using tool_choice: auto. A preserved-thinking mismatch alert should tell operators not to replay the raw transcript into Fable 5 or another older model. A cost spike alert should show whether the driver is output length, effort selection, cache misses, or batch traffic moving to synchronous traffic.

Prepare rollback without corrupting conversation state

Rollback is straightforward for stateless single-turn requests: route new requests back to the previous production model and keep Fable 5.1 traces for postmortem analysis. Rollback is harder for long-running conversations because Fable 5.1 thinking blocks are not backward-compatible with older models. Your rollback plan should therefore specify which sessions can continue on Fable 5.1 until completion, which sessions must be summarized into a clean fallback transcript, and which sessions require user confirmation before restarting.

Keep feature flags separate. One flag should control the model ID, another should control per-message effort, another should control turn-scoped system messages, and another should control progress updates. This separation lets you disable a beta feature that causes UI or tracing defects without abandoning the base Fable 5.1 migration. It also makes incident review more precise because the timeline can show exactly when a model change occurred versus when a new beta control was enabled.

Acceptance criteria for production migration

• API compatibility: no production request uses forced tool choice with any or a named tool; all tool-routing paths use auto plus strict schemas or structured outputs.
• Transcript safety: append-only history is enforced for preserved-thinking sessions, and older-model fallback never consumes Fable 5.1 thinking blocks.
• Retention approval: 30-day retention requirements and any authorized ZDR exceptions are documented for each workload class before launch.
• Cost evidence: dashboards show input, output, cache-write, cache-read, effort-level, and batch-versus-online spend for canary traffic.
• Behavioral review: refusal, tool-call, and final-answer samples have been reviewed for the highest-risk workflow categories.
• Observability: request traces include model ID, beta headers, token counts, retries, fallback target, and progress-update handling where enabled.
• Rollback readiness: operators can disable Fable 5.1 routing or individual beta controls without replaying incompatible transcripts into older models.

The safest Fable 5.1 migration is incremental: first prove that the Fable 5 workload works with the new model ID and breaking-change fixes, then add effort controls, turn-scoped instructions, and progress updates only where they solve a measured problem. Anthropic’s documentation gives teams useful new levers for long-context and agentic systems, but production reliability still depends on your harness: append-only state, schema validation, retention governance, cost telemetry, human checkpoints, and a rollback path that respects preserved-thinking compatibility.

Useful Links

• Anthropic Claude Fable 5.1 migration guide
• Anthropic: what’s new in Claude Fable 5.1
• Anthropic prompting guide for Claude Fable 5.1