One read of Claude Developer Platformapi-20261112T160709Z
52 pages moved out of 904 read.
Pages moved
52
significant first
Pages read
904
in this capture
Captured
16:07 UTC
Corpus hash
0908a26ac580
corpus-hash
What this read moved
26-50 of 52, page 2 of 3This capture is too large to show at once. Changes 26-50 of 52 are below, significant first; the rest are on the following screens.
build-with-claude/streaming Changed · +3 / -3 lines
from line 325
325325
326326Each stream uses the following event flow:
327327
3281. `message_start`: contains a `Message` object with empty `content`. Under the [`thinking-binding-controls-2026-08-01`](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking-controls) beta header, this `Message` object also carries the `input_transformations` array. After a mid-stream [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback), the final `message_delta` event carries the array again with the serving model’s entries.
3292. A series of content blocks, each of which has a `content_block_start`, one or more `content_block_delta` events, and a `content_block_stop` event. Each content block has an `index` that corresponds to its index in the final Message `content` array. One exception: during [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback) responses, a `fallback` content block arrives at each model boundary as a `content_block_start` and `content_block_stop` pair with no deltas in between.
3281. `message_start`: contains a `Message` object with empty `content`. Under the [`thinking-binding-controls-2026-08-01`](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#preserved-thinking-controls) beta header, this `Message` object also carries the `input_transformations` array. After a mid-stream [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback), the final `message_delta` event carries the array again with the serving model’s entries.
3292. A series of content blocks, each of which has a `content_block_start`, any number of `content_block_delta` events, and a `content_block_stop` event. Each content block has an `index` that corresponds to its index in the final Message `content` array. Some blocks arrive whole, with no deltas: `redacted_thinking` blocks, server tool results such as `web_search_tool_result`, and the `fallback` block at each model boundary of a [server-side fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#server-side-fallback).
3303303. One or more `message_delta` events, indicating top-level changes to the final `Message` object.
3313314. A final `message_stop` event.
332332
from line 377
377377data: {"type": "content_block_delta","index": 1,"delta": {"type": "input_json_delta","partial_json": "{\"location\": \"San Fra"}}}
378378```
379379
380Note: Current models only support emitting one complete key and value property from `input` at a time. As such, when using tools, there might be delays between streaming events while the model is working. Once an `input` key and value are accumulated, they are emitted as multiple `content_block_delta` events with chunked partial JSON so that the format can automatically support finer granularity in future models.
380By default, the API buffers each key and value in `input` until it is complete. With tools, there might be delays between streaming events while the model generates a value. Once the API has a complete `input` key and value, it emits them as multiple `content_block_delta` events with chunked partial JSON.
381381
382382### Thinking delta
383383
build-with-claude/structured-outputs Changed · +346 / -84 lines
#### Objects with arbitrary keys
The two sides of this change are more than 400 edits apart, too far apart to line up, so this is the differ's own diff of it and the words inside a line are not marked.
from line 55
5555
5656Structured outputs guarantee schema-compliant responses through constrained decoding:
5757
58* **Always valid:** No more `JSON.parse()` errors
58* **Always valid:** No JSON parsing errors
5959* **Type safe:** Guaranteed field types and required fields
6060* **Reliable:** No retries needed for schema violations
6161
from line 203
203203 ```text Output wrap
205205 ```
206
207 If you know a field’s keys, use a nested Pydantic model, not a `dict`. The SDK sends a `dict` field as an object with empty `properties`, so Claude can only return `{}` for it. If you don’t know the keys in advance, see [Objects with arbitrary keys](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#objects-with-arbitrary-keys).
206208 </Tab>
207209
208210 <Tab title="TypeScript">
from line 244
242244
243245 The previous example outputs:
244246
245 ```javascript Output
247 ```text Output wrap
246248 {
247249 name: 'John Smith',
from line 252
250252 demo_requested: true
251253 }
252254 ```
255
256 If you know a field’s keys, use `z.object()`, not `z.record()`. The SDK sends a `z.record()` field as an object with empty `properties`, so Claude can only return `{}` for it. If you don’t know the keys in advance, see [Objects with arbitrary keys](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#objects-with-arbitrary-keys).
253257 </Tab>
254258
255259 <Tab title="C#">
from line 401
397401
398402 Key points:
399403
400 * **Local validation** occurs without sending requests to the remote AI model.
401 * **Remote validation** is also performed by the AI model upon receiving the JSON schema.
404 * **Local validation:** The SDK validates the schema without sending a request.
405 * **Remote validation:** The API also validates the JSON schema when it receives the request.
402406 * **Version compatibility:** If the SDK version is outdated, local validation might reject a schema that remote validation accepts.
403407 * **Disabling local validation:** Pass `JsonSchemaLocalValidation.NO` if you encounter compatibility issues:
404408
from line 446
442446 * There are no fields or getter methods in the class
443447 * All `public` members are annotated with `@JsonIgnore`
444448 * All non-`public` members lack `@JsonProperty` annotations
445 * A field uses a `Map` type, which produces an empty `"properties"` field
449 * A field uses a `Map` type, which produces an empty `"properties"` field (to avoid this, see [Objects with arbitrary keys](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#objects-with-arbitrary-keys))
446450 </Accordion>
447451
448452 <Accordion title="Composition and inheritance">
from line 697
694698 "and wants to schedule a demo for next Tuesday at 2pm."
695699 }],
696 output_config: {format: ContactInfo}
700 output_config: { format: ContactInfo }
697701 )
698702
699703 contact = message.parsed_output
700704 puts contact
701705 ```
702706
703 Define a class that extends `Anthropic::BaseModel` and pass it to `messages.create()` as `output_config: {format: Model}`. The SDK derives a JSON schema from the class, transforms it, and assigns the parsed result to the response’s `parsed_output` attribute as a typed Ruby object.
707 Define a class that extends `Anthropic::BaseModel` and pass it to `messages.create()` as `output_config: { format: Model }`. The SDK derives a JSON schema from the class, transforms it, and assigns the parsed result to the response’s `parsed_output` attribute as a typed Ruby object.
704708
705709 The previous example outputs:
706710
from line 733
729733 message = client.messages.create(
730734 model: Anthropic::Model::CLAUDE_OPUS_5_5,
731735 max_tokens: 1024,
732 messages: [{role: "user", content: "give me some famous numbers"}],
733 output_config: {format: Output}
736 messages: [{ role: "user", content: "give me some famous numbers" }],
737 output_config: { format: Output }
734738 )
735739
736740 message.parsed_output
from line 934
930934
931935 The previous example outputs:
932936
933 ```javascript Output
937 ```text Output wrap
935939 ```
936940 </Tab>
from line 1141
11371141 ])),
11381142 );
11391143
1140 $textBlock = array_find($message->content, static fn ($block): bool => $block->type === 'text');
1144 $textBlock = array_find($message->content, static fn ($block): bool => $block instanceof \Anthropic\Messages\TextBlock)
1145 ?? throw new \RuntimeException('Expected a text block in the response.');
11411146 $contact = json_decode($textBlock->text, associative: true);
11421147 var_dump($contact);
11431148 ```
11441149
1145 Pass the schema as an associative array to `OutputConfig::with()`, and decode the response with `json_decode()`.
1150 Pass the schema as an associative array to `JSONOutputFormat::with()` inside `OutputConfig::with()`, and decode the response with `json_decode()`.
11461151
11471152 The previous example outputs:
11481153
from line 1227
12221227 "messages": [
12231228 {
12241229 "role": "user",
1225 "content": "Extract invoice data from: Invoice #12345, Date: 2024-01-15, Total: $500.00"
1230 "content": "Extract invoice data from: Invoice #12345, Date: 2024-01-15, Customer: Acme Corp, 2 widgets at $150.00 each, 1 setup fee at $200.00, Total: $500.00"
12261231 }
12271232 ],
12281233 "output_config": {
from line 1241
12361241 "total_amount": {"type": "number"},
12371242 "line_items": {
12381243 "type": "array",
1239 "items": {"type": "object", "additionalProperties": false}
1244 "items": {
1245 "type": "object",
1246 "properties": {
1247 "description": {"type": "string"},
1248 "quantity": {"type": "number"},
1249 "unit_price": {"type": "number"}
1250 },
1251 "required": ["description", "quantity", "unit_price"],
1252 "additionalProperties": false
1253 }
12401254 },
12411255 "customer_name": {"type": "string"}
12421256 },
from line 1268
12541268 max_tokens: 4096
12551269 messages:
12561270 - role: user
1257 content: "Extract invoice data from: Invoice #12345, Date: 2024-01-15, Total: $500.00"
1271 content: |
1272 Extract invoice data from:
1273 Invoice #12345
1274 Date: 2024-01-15
1275 Customer: Acme Corp
1276 2 widgets at $150.00 each
1277 1 setup fee at $200.00
1278 Total: $500.00
12581279 output_config:
12591280 format:
12601281 type: json_schema
from line 1287
12661287 total_amount: {type: number}
12671288 line_items:
12681289 type: array
1269 items: {type: object, additionalProperties: false}
1290 items:
1291 type: object
1292 properties:
1293 description: {type: string}
1294 quantity: {type: number}
1295 unit_price: {type: number}
1296 required: [description, quantity, unit_price]
1297 additionalProperties: false
12701298 customer_name: {type: string}
12711299 required: [invoice_number, date, total_amount, line_items, customer_name]
12721300 additionalProperties: false
from line 1305
12771305 from pydantic import BaseModel
12781306
12791307
1308 class LineItem(BaseModel):
1309 description: str
1310 quantity: float
1311 unit_price: float
1312
1313
12801314 class Invoice(BaseModel):
12811315 invoice_number: str
12821316 date: str
12831317 total_amount: float
1284 line_items: list[dict]
1318 line_items: list[LineItem]
12851319 customer_name: str
12861320
12871321
12881322 client = anthropic.Anthropic()
1289 invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"
1323 invoice_text = """
1324 Invoice #12345
1325 Date: 2024-01-15
1326 Customer: Acme Corp
1327 2 widgets at $150.00 each
1328 1 setup fee at $200.00
1329 Total: $500.00
1330 """
12901331
12911332 response = client.messages.parse(
12921333 model="claude-opus-5-5",
from line 1347
13061347
13071348 const client = new Anthropic();
13081349
1350 const LineItemSchema = z.object({
1351 description: z.string(),
1352 quantity: z.number(),
1353 unit_price: z.number()
1354 });
1355
13091356 const InvoiceSchema = z.object({
13101357 invoice_number: z.string(),
13111358 date: z.string(),
13121359 total_amount: z.number(),
1313 line_items: z.array(z.record(z.string(), z.any())),
1360 line_items: z.array(LineItemSchema),
13141361 customer_name: z.string()
13151362 });
13161363
1317 const invoiceText = "Invoice #12345, Date: 2024-01-15, Total: $500.00";
1364 const invoiceText = `
1365 Invoice #12345
1366 Date: 2024-01-15
1367 Customer: Acme Corp
1368 2 widgets at $150.00 each
1369 1 setup fee at $200.00
1370 Total: $500.00
1371 `;
1372
13181373 const response = await client.messages.parse({
13191374 model: "claude-opus-5-5",
13201375 max_tokens: 4096,
from line 1382
13271382 ```csharp C#
13281383 AnthropicClient client = new();
13291384
1330 string invoiceText = "Invoice #12345, Date: 2024-01-15, Total: $500.00";
1385 string invoiceText = """
1386 Invoice #12345
1387 Date: 2024-01-15
1388 Customer: Acme Corp
1389 2 widgets at $150.00 each
1390 1 setup fee at $200.00
1391 Total: $500.00
1392 """;
13311393
13321394 var parameters = new MessageCreateParams
13331395 {
from line 1413
13511413 items = new
13521414 {
13531415 type = "object",
1416 properties = new
1417 {
1418 description = new { type = "string" },
1419 quantity = new { type = "number" },
1420 unit_price = new { type = "number" },
1421 },
1422 required = new[] { "description", "quantity", "unit_price" },
13541423 additionalProperties = false,
13551424 },
13561425 },
from line 1440
13711440 ```go Go
13721441 client := anthropic.NewClient()
13731442
1374 invoiceText := "Invoice #12345, Date: 2024-01-15, Total: $500.00"
1443 invoiceText := `
1444 Invoice #12345
1445 Date: 2024-01-15
1446 Customer: Acme Corp
1447 2 widgets at $150.00 each
1448 1 setup fee at $200.00
1449 Total: $500.00
1450 `
13751451
13761452 schema := map[string]any{
13771453 "type": "object",
from line 1505
14291505 public String description;
14301506
14311507 @JsonProperty("quantity")
1432 public int quantity;
1508 public double quantity;
14331509
14341510 @JsonProperty("unit_price")
14351511 public double unitPrice;
from line 1531
14551531 void main() {
14561532 AnthropicClient client = AnthropicOkHttpClient.fromEnv();
14571533
1458 String invoiceText = "Invoice #12345, Date: 2024-01-15, Total: $500.00";
1534 String invoiceText = """
1535 Invoice #12345
1536 Date: 2024-01-15
1537 Customer: Acme Corp
1538 2 widgets at $150.00 each
1539 1 setup fee at $200.00
1540 Total: $500.00
1541 """;
14591542
14601543 StructuredMessageCreateParams<Invoice> params = MessageCreateParams.builder()
14611544 .model(Model.CLAUDE_OPUS_5_5)
from line 1551
14681551 Invoice invoice = response.content().stream()
14691552 .flatMap(block -> block.text().stream())
14701553 .findFirst().orElseThrow().text();
1471 IO.println(invoice.invoiceNumber + ": $" + invoice.totalAmount);
1554 IO.println("Invoice " + invoice.invoiceNumber + ": $" + invoice.totalAmount);
1555 for (LineItem item : invoice.lineItems) {
1556 IO.println(item.quantity + " x " + item.description);
1557 }
14721558 }
14731559 ```
14741560
14751561 ```php PHP
1562 use Anthropic\Lib\Attributes\Constrained;
14761563 use Anthropic\Lib\Concerns\StructuredOutputModelTrait;
14771564 use Anthropic\Lib\Contracts\StructuredOutputModel;
14781565
14791566 $client = new Client();
1567
1568 class LineItem implements StructuredOutputModel
1569 {
1570 use StructuredOutputModelTrait;
1571
1572 public string $description;
1573 public float $quantity;
1574 public float $unit_price;
1575 }
14801576
14811577 class Invoice implements StructuredOutputModel
14821578 {
from line 1581
14851581 public string $invoice_number;
14861582 public string $date;
14871583 public float $total_amount;
1584 #[Constrained(itemClass: LineItem::class)]
14881585 public array $line_items;
14891586 public string $customer_name;
14901587 }
14911588
1492 $invoiceText = "Invoice #12345, Date: 2024-01-15, Total: $500.00";
1589 $invoiceText = <<<'TEXT'
1590 Invoice #12345
1591 Date: 2024-01-15
1592 Customer: Acme Corp
1593 2 widgets at $150.00 each
1594 1 setup fee at $200.00
1595 Total: $500.00
1596 TEXT;
14931597
14941598 $message = $client->messages->create(
14951599 maxTokens: 4096,
from line 1607
15031607 $invoice = $message->parsedOutput();
15041608 if ($invoice instanceof Invoice) {
15051609 echo "Invoice {$invoice->invoice_number}: \${$invoice->total_amount}\n";
1610 foreach ($invoice->line_items as $item) {
1611 echo "{$item->quantity} x {$item->description}\n";
1612 }
15061613 }
15071614 ```
15081615
from line 1618
15111618
15121619 class LineItem < Anthropic::BaseModel
15131620 required :description, String
1514 required :amount, Float
1621 required :quantity, Float
1622 required :unit_price, Float
15151623 end
15161624
15171625 class Invoice < Anthropic::BaseModel
from line 1630
15221630 required :customer_name, String
15231631 end
15241632
1525 invoice_text = "Invoice #12345, Date: 2024-01-15, Total: $500.00"
1633 invoice_text = <<~TEXT
1634 Invoice #12345
1635 Date: 2024-01-15
1636 Customer: Acme Corp
1637 2 widgets at $150.00 each
1638 1 setup fee at $200.00
1639 Total: $500.00
1640 TEXT
15261641
15271642 message = client.messages.create(
15281643 model: Anthropic::Model::CLAUDE_OPUS_5_5,
15291644 max_tokens: 4096,
1530 output_config: {format: Invoice},
1645 output_config: { format: Invoice },
15311646 messages: [
1532 {role: "user", content: "Extract invoice data from: #{invoice_text}"}
1647 { role: "user", content: "Extract invoice data from: #{invoice_text}" }
15331648 ]
15341649 )
15351650
15361651 invoice = message.parsed_output
15371652 puts "Invoice #{invoice.invoice_number}: $#{invoice.total_amount}"
1653 invoice.line_items.each { |item| puts "#{item.quantity} x #{item.description}" }
15381654 ```
15391655 </CodeGroup>
15401656 </Accordion>
from line 1773
16571773 ```
16581774
16591775 ```csharp C#
1776 AnthropicClient client = new();
1777
16601778 string feedbackText = "Great product, fast shipping!";
16611779
16621780 var parameters = new MessageCreateParams
from line 1808
16901808 ```
16911809
16921810 ```go Go
1811 client := anthropic.NewClient()
1812
16931813 feedbackText := "Great product, fast shipping!"
16941814
16951815 schema := map[string]any{
from line 1934
18141934 message = client.messages.create(
18151935 model: Anthropic::Model::CLAUDE_OPUS_5_5,
18161936 max_tokens: 1024,
1817 output_config: {format: Classification},
1937 output_config: { format: Classification },
18181938 messages: [
1819 {role: "user", content: "Classify this feedback: #{feedback_text}"}
1939 { role: "user", content: "Classify this feedback: #{feedback_text}" }
18201940 ]
18211941 )
18221942 puts message.parsed_output
from line 1959
18391959 "messages": [
18401960 {
18411961 "role": "user",
1842 "content": "Process this request: ..."
1962 "content": "Write an API response: request req_2abc3def has an invalid email."
18431963 }
18441964 ],
18451965 "output_config": {
from line 1969
18491969 "type": "object",
18501970 "properties": {
18511971 "status": {"type": "string"},
1852 "data": {"type": "object", "additionalProperties": false},
1972 "data": {
1973 "type": "object",
1974 "properties": {"message": {"type": "string"}},
1975 "required": ["message"],
1976 "additionalProperties": false
1977 },
18531978 "errors": {
18541979 "type": "array",
1855 "items": {"type": "object", "additionalProperties": false}
1980 "items": {
1981 "type": "object",
1982 "properties": {
1983 "code": {"type": "string"},
1984 "detail": {"type": "string"}
1985 },
1986 "required": ["code", "detail"],
1987 "additionalProperties": false
1988 }
18561989 },
1857 "metadata": {"type": "object", "additionalProperties": false}
1990 "metadata": {
1991 "type": "object",
1992 "properties": {"request_id": {"type": "string"}},
1993 "required": ["request_id"],
1994 "additionalProperties": false
1995 }
18581996 },
18591997 "required": ["status", "data", "metadata"],
18601998 "additionalProperties": false
from line 2016
18782016 type: string
18792017 data:
18802018 type: object
2019 properties:
2020 message:
2021 type: string
2022 required:
2023 - message
18812024 additionalProperties: false
18822025 errors:
18832026 type: array
18842027 items:
18852028 type: object
2029 properties:
2030 code:
2031 type: string
2032 detail:
2033 type: string
2034 required:
2035 - code
2036 - detail
18862037 additionalProperties: false
18872038 metadata:
18882039 type: object
2040 properties:
2041 request_id:
2042 type: string
2043 required:
2044 - request_id
18892045 additionalProperties: false
18902046 required:
18912047 - status
from line 2050
18942050 additionalProperties: false
18952051 messages:
18962052 - role: user
1897 content: "Process this request: ..."
2053 content: "Write an API response: request req_2abc3def has an invalid email."
18982054 YAML
18992055 ```
19002056
from line 2060
19042060 client = Anthropic()
19052061
19062062
2063 class Payload(BaseModel):
2064 message: str
2065
2066
2067 class APIError(BaseModel):
2068 code: str
2069 detail: str
2070
2071
2072 class Metadata(BaseModel):
2073 request_id: str
2074
2075
19072076 class APIResponse(BaseModel):
19082077 status: str
1909 data: dict
1910 errors: list[dict] | None
1911 metadata: dict
2078 data: Payload
2079 errors: list[APIError] | None = None
2080 metadata: Metadata
19122081
19132082
19142083 response = client.messages.parse(
19152084 model="claude-opus-5-5",
19162085 max_tokens=1024,
19172086 output_format=APIResponse,
1918 messages=[{"role": "user", "content": "Process this request: ..."}],
2087 messages=[
2088 {
2089 "role": "user",
2090 "content": "Write an API response: request req_2abc3def has an invalid email.",
2091 }
2092 ],
19192093 )
19202094
19212095 print(response.parsed_output)
from line 2103
19292103
19302104 const APIResponseSchema = z.object({
19312105 status: z.string(),
1932 data: z.record(z.string(), z.any()),
1933 errors: z.array(z.record(z.string(), z.any())).optional(),
1934 metadata: z.record(z.string(), z.any())
2106 data: z.object({ message: z.string() }),
2107 errors: z.array(z.object({ code: z.string(), detail: z.string() })).optional(),
2108 metadata: z.object({ request_id: z.string() })
19352109 });
19362110
19372111 const response = await client.messages.parse({
19382112 model: "claude-opus-5-5",
19392113 max_tokens: 1024,
19402114 output_config: { format: zodOutputFormat(APIResponseSchema) },
1941 messages: [{ role: "user", content: "Process this request..." }]
2115 messages: [
2116 {
2117 role: "user",
2118 content: "Write an API response: request req_2abc3def has an invalid email."
2119 }
2120 ]
19422121 });
19432122
19442123 console.log(response.parsed_output);
19452124 ```
19462125
19472126 ```csharp C#
2127 AnthropicClient client = new();
2128
19482129 var parameters = new MessageCreateParams
19492130 {
19502131 Model = Model.ClaudeOpus5_5,
19512132 MaxTokens = 1024,
1952 Messages = [new UserMessageParam { Content = "Process this request: ..." }],
2133 Messages =
2134 [
2135 new UserMessageParam
2136 {
2137 Content = "Write an API response: request req_2abc3def has an invalid email.",
2138 },
2139 ],
19532140 OutputConfig = new OutputConfig
19542141 {
19552142 Format = new JsonOutputFormat
from line 2147
19602147 ["properties"] = JsonSerializer.SerializeToElement(new
19612148 {
19622149 status = new { type = "string" },
1963 data = new { type = "object", additionalProperties = false },
2150 data = new
2151 {
2152 type = "object",
2153 properties = new { message = new { type = "string" } },
2154 required = new[] { "message" },
2155 additionalProperties = false,
2156 },
19642157 errors = new
19652158 {
19662159 type = "array",
1967 items = new { type = "object", additionalProperties = false },
2160 items = new
2161 {
2162 type = "object",
2163 properties = new
2164 {
2165 code = new { type = "string" },
2166 detail = new { type = "string" },
2167 },
2168 required = new[] { "code", "detail" },
2169 additionalProperties = false,
2170 },
19682171 },
1969 metadata = new { type = "object", additionalProperties = false },
2172 metadata = new
2173 {
2174 type = "object",
2175 properties = new { request_id = new { type = "string" } },
2176 required = new[] { "request_id" },
2177 additionalProperties = false,
2178 },
19702179 }),
19712180 ["required"] = JsonSerializer.SerializeToElement(new[] { "status", "data", "metadata" }),
19722181 ["additionalProperties"] = JsonSerializer.SerializeToElement(false),
from line 2206
19972206 "data": map[string]any{
19982207 "type": "object",
19992208 "additionalProperties": false,
2209 "properties": map[string]any{
2210 "message": map[string]any{"type": "string"},
2211 },
2212 "required": []string{"message"},
20002213 },
20012214 "errors": map[string]any{
20022215 "type": "array",
20032216 "items": map[string]any{
20042217 "type": "object",
20052218 "additionalProperties": false,
2219 "properties": map[string]any{
2220 "code": map[string]any{"type": "string"},
2221 "detail": map[string]any{"type": "string"},
2222 },
2223 "required": []string{"code", "detail"},
20062224 },
20072225 },
20082226 "metadata": map[string]any{
20092227 "type": "object",
20102228 "additionalProperties": false,
2229 "properties": map[string]any{
2230 "request_id": map[string]any{"type": "string"},
2231 },
2232 "required": []string{"request_id"},
20112233 },
20122234 },
20132235 "required": []string{"status", "data", "metadata"},
from line 2237
20152237 },
20162238 },
20172239 Messages: []anthropic.MessageParam{
2018 anthropic.NewUserMessage(anthropic.NewTextBlock("Process this request: ...")),
2240 anthropic.NewUserMessage(anthropic.NewTextBlock(
2241 "Write an API response: request req_2abc3def has an invalid email.",
2242 )),
20192243 },
20202244 })
20212245 if err != nil {
from line 2256
20322256 ```java Java
20332257 import com.fasterxml.jackson.annotation.JsonProperty;
20342258
2035 static class APIData {
2259 static class Payload {
20362260 @JsonProperty("message")
20372261 public String message;
2038
2039 @JsonProperty("resource_id")
2040 public String resourceId;
20412262 }
20422263
20432264 static class APIError {
20442265 @JsonProperty("code")
20452266 public String code;
20462267
2047 @JsonProperty("message")
2048 public String message;
2049 }
2050
2051 static class APIMetadata {
2268 @JsonProperty("detail")
2269 public String detail;
2270 }
2271
2272 static class Metadata {
20522273 @JsonProperty("request_id")
20532274 public String requestId;
2054
2055 @JsonProperty("timestamp")
2056 public String timestamp;
20572275 }
20582276
20592277 static class APIResponse {
from line 2279
20612279 public String status;
20622280
20632281 @JsonProperty("data")
2064 public APIData data;
2282 public Payload data;
20652283
20662284 @JsonProperty("errors")
20672285 public List<APIError> errors;
20682286
20692287 @JsonProperty("metadata")
2070 public APIMetadata metadata;
2288 public Metadata metadata;
20712289 }
20722290
20732291 void main() {
from line 2295
20772295 .model(Model.CLAUDE_OPUS_5_5)
20782296 .maxTokens(1024L)
20792297 .outputConfig(APIResponse.class)
2080 .addUserMessage("Process this request: ...")
2298 .addUserMessage("Write an API response: request req_2abc3def has an invalid email.")
20812299 .build();
20822300
20832301 StructuredMessage<APIResponse> response = client.messages().create(params);
20842302 APIResponse result = response.content().stream()
20852303 .flatMap(block -> block.text().stream())
20862304 .findFirst().orElseThrow().text();
2087 IO.println(result.status);
2305 IO.println(result.status + ": " + result.data.message);
20882306 }
20892307 ```
20902308
from line 2313
20952313
20962314 $client = new Client();
20972315
2098 class Payload implements StructuredOutputModel { use StructuredOutputModelTrait; public string $message; }
2099
2100 class APIError implements StructuredOutputModel { use StructuredOutputModelTrait; public string $code; public string $detail; }
2101
2102 class Metadata implements StructuredOutputModel { use StructuredOutputModelTrait; public string $request_id; }
2316 class Payload implements StructuredOutputModel
2317 {
2318 use StructuredOutputModelTrait;
2319
2320 public string $message;
2321 }
2322
2323 class APIError implements StructuredOutputModel
2324 {
2325 use StructuredOutputModelTrait;
2326
2327 public string $code;
2328 public string $detail;
2329 }
2330
2331 class Metadata implements StructuredOutputModel
2332 {
2333 use StructuredOutputModelTrait;
2334
2335 public string $request_id;
2336 }
21032337
21042338 class APIResponse implements StructuredOutputModel
21052339 {
from line 2349
21152349 $message = $client->messages->create(
21162350 maxTokens: 1024,
21172351 messages: [
2118 ['role' => 'user', 'content' => 'Process this request: ...']
2352 [
2353 'role' => 'user',
2354 'content' => 'Write an API response: request req_2abc3def has an invalid email.',
2355 ],
21192356 ],
21202357 model: 'claude-opus-5-5',
21212358 outputConfig: ['format' => APIResponse::class],
from line 2390
21532390 message = client.messages.create(
21542391 model: Anthropic::Model::CLAUDE_OPUS_5_5,
21552392 max_tokens: 1024,
2156 output_config: {format: APIResponse},
2393 output_config: { format: APIResponse },
21572394 messages: [
2158 {role: "user", content: "Process this request: ..."}
2395 { role: "user", content: "Write an API response: request req_2abc3def has an invalid email." }
21592396 ]
21602397 )
21612398 puts message.parsed_output
from line 2604
23672604 ```
23682605
23692606 ```csharp C#
2607 AnthropicClient client = new();
2608
23702609 var parameters = new MessageCreateParams
23712610 {
23722611 Model = Model.ClaudeOpus5_5,
from line 2802
25632802 model: Anthropic::Model::CLAUDE_OPUS_5_5,
25642803 max_tokens: 1024,
25652804 messages: [
2566 {role: "user", content: "Help me plan a trip to Paris departing May 15, 2026"}
2805 { role: "user", content: "Help me plan a trip to Paris departing May 15, 2026" }
25672806 ],
25682807 # JSON outputs: structured response format
25692808 output_config: {
from line 2811
25722811 schema: {
25732812 type: "object",
25742813 properties: {
2575 summary: {type: "string"},
2576 next_steps: {type: "array", items: {type: "string"}}
2814 summary: { type: "string" },
2815 next_steps: { type: "array", items: { type: "string" } }
25772816 },
25782817 required: ["summary", "next_steps"],
25792818 additionalProperties: false
from line 2827
25882827 input_schema: {
25892828 type: "object",
25902829 properties: {
2591 destination: {type: "string"},
2592 date: {type: "string", format: "date"}
2830 destination: { type: "string" },
2831 date: { type: "string", format: "date" }
25932832 },
25942833 required: ["destination", "date"],
25952834 additionalProperties: false
from line 2856
26172856
26182857* Your input token count is slightly higher.
26192858* The injected prompt costs you tokens like any other system prompt.
2620* Changing the `output_config.format` parameter will invalidate any [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for that conversation thread.
2859* Changing the `output_config.format` parameter invalidates any [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) for that conversation thread.
26212860
26222861### JSON Schema limitations
26232862
from line 2881
26422881 * Numerical constraints (such as `minimum`, `maximum`, `multipleOf`)
26432882 * String constraints (`minLength`, `maxLength`)
26442883 * Array constraints beyond `minItems` of 0 or 1
2645 * `additionalProperties` set to anything other than `false`
2884 * `additionalProperties` set to anything other than `false` (see [Objects with arbitrary keys](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#objects-with-arbitrary-keys))
26462885
26472886 If you use an unsupported feature, you’ll receive a 400 error with details.
26482887</Accordion>
from line 2907
26682907<Tip>
26692908 SDK helpers can transform schemas with [constraints not supported by the API](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#json-schema-limitations). See [How SDK transformation works](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#how-sdk-transformation-works).
26702909</Tip>
2910
2911#### Objects with arbitrary keys
2912
2913List every key of an object, either in `properties` or as a field of the class or schema you pass to the SDK. Because `additionalProperties` must be `false`, Claude can only return the keys you list.
2914
2915The API accepts an object with empty or missing `properties`, but Claude can only return `{}` for it. A map, dictionary, or record type lists no keys, so the Python and TypeScript SDKs send it as an object with empty `properties`. The Java and Ruby SDKs raise an error instead.
2916
2917If you don’t know the keys in advance, use an array instead. Give each item a `key` and a `value`, as in this schema:
2918
2919```json
2920{
2921 "type": "array",
2922 "items": {
2923 "type": "object",
2924 "properties": {
2925 "key": { "type": "string" },
2926 "value": { "type": "string" }
2927 },
2928 "required": ["key", "value"],
2929 "additionalProperties": false
2930 }
2931}
2932```
26712933
26722934### Property ordering
26732935
from line 2951
26892951}
26902952```
26912953
2692The output will order properties as:
2954The output orders properties as:
26932955
269429561. `name` (required, in schema order)
269529572. `email` (required, in schema order)
from line 3022
27603022| Parameters with union types | 16 | Total parameters that use `anyOf` or type arrays (for example, `"type": ["string", "null"]`) across all strict schemas. These are especially expensive because they create exponential compilation cost. |
27613023
27623024<Note>
2763 These limits apply to the combined total across all strict schemas in a single request. For example, if you have 4 strict tools with 6 optional parameters each, you’ll reach the 24-parameter limit even though no single tool seems complex.
3025 These limits apply to the combined total across all strict schemas in a single request. For example, if you have four strict tools with six optional parameters each, you’ll reach the 24-parameter limit even though no single tool seems complex.
27643026</Note>
27653027
27663028#### Additional internal limits
from line 3049
27873049
27883050The `output_format` parameter has moved to `output_config.format`, and beta headers are no longer required. The `output_format` parameter is deprecated. To use it anyway, add the `structured-outputs-2025-11-13` beta header. Without it, the API returns a 400 error.
27893051
2790The Python SDK (v1.0 and later) does not accept `output_format={...}` on `client.beta.messages.create()` or `count_tokens()` and raises a `TypeError`. Use `output_config` instead. See [Using a raw JSON schema](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#using-a-raw-json-schema) for the updated API shape.
3052In the Python SDK (v1.0 and later), a schema dictionary passed as `output_format={...}` raises a `TypeError`. Use `output_config` instead. A Pydantic model passed as `output_format=Model` to `parse()` or `stream()` works with no change and no beta header, because the SDK sends it as `output_config`. See [Using a raw JSON schema](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#using-a-raw-json-schema) for the updated API shape.
27913053
27923054## Feature compatibility
27933055
27943056
build-with-claude/thinking Changed · +28 / -34 lines
from line 980
980980
981981* **Required:** within a tool-use turn, pass thinking blocks back.
982982* **Recommended:** across turns, pass everything back.
983* **Allowed:** outside tool use, omit prior turns’ thinking.
983* **Allowed:** outside tool use, omit prior turns’ thinking, but not a block between two that you keep.
984984
985985You don’t need to prune old thinking yourself. Pass all thinking blocks back in multi-turn conversations, and the API automatically filters them, keeps the blocks needed to preserve the model’s reasoning, and bills input tokens only for the blocks actually shown to Claude. Which prior-turn blocks are kept is per-model. See [Thinking block preservation by model](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model). To override the default, use the [`clear_thinking_20251015` context-editing strategy](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing).
986986
from line 987
987987Within the latest assistant message, the sequence of consecutive `thinking` blocks must match what the model generated in the original request: you can’t rearrange, edit, or partially drop them. This includes [`redacted_thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#redacted-thinking-blocks).
988988
989989<Note>
990 Modified thinking blocks are rejected with a 400 error. See [A 400 error says thinking blocks cannot be modified](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified) for the exact message, the common causes, and the fix. The one exception: text placed in the empty `thinking` field of an [omitted](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) block is ignored rather than rejected.
990 Modified thinking blocks are rejected with a 400 error. See [A 400 error says thinking blocks cannot be modified](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#error-thinking-blocks-modified) for the exact message and the fix. The one exception: text placed in the empty `thinking` field of an [omitted](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) block is ignored rather than rejected.
991991</Note>
992992
993993For a worked example with code in every SDK, see [Walk through a two-turn tool-use round trip](https://platform.claude.com/docs/en/build-with-claude/thinking-tool-workflows#two-turn-tool-use-round-trip). It defines a tool, receives a thinking-plus-tool-use response, and echoes the assistant turn back with the tool result.
from line 1102
11021102
11031103The tradeoff is context usage: long conversations consume more context space on keep-all models, because retained thinking blocks count as input like any other conversation history (see [Thinking and the context window](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-the-context-window)). The behavior is automatic in both regimes. Keep passing complete, unmodified thinking blocks back, as described in [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks). To override the default in either direction, use [thinking block clearing](https://platform.claude.com/docs/en/build-with-claude/context-editing#thinking-block-clearing).
11041104
1105**Switching models mid-conversation.** Keep passing thinking blocks back unchanged when you switch models, for example after a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback). A thinking block is readable only by the model that produced it and certain other models. The API ignores or drops the blocks that the target model can’t read (see [how dropped blocks are billed and reported](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). The following list says, for each model in it, what the model reads and which models read its blocks:
1105**Switching models mid-conversation.** Keep passing thinking blocks back unchanged when you switch models, for example after a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback). A thinking block is readable only by the model that produced it and certain other models. The API ignores or drops the blocks that the target model can’t read (see [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). The following list says, for each model in it, what the model reads and which models read its blocks:
11061106
11071107* **Claude Fable 5.2 and Claude Mythos 5.2:** On the Claude API and Claude Models on Google Cloud (Google managed), they read each other’s thinking blocks. There, they also read blocks from other models, including Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5. No other model reads Claude Fable 5.2 or Claude Mythos 5.2 blocks. So a switch from either to a model outside this pair drops the earlier turns’ reasoning.
1108* **Claude Fable 5.1 and Claude Mythos 5.1:** They read each other’s thinking blocks and those of earlier models, except Claude Mythos Preview’s. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 also read their blocks. No other model does. A switch to Claude Fable 5.1 or Claude Mythos 5.1 from a model whose blocks they read keeps the conversation’s reasoning. A switch from either to a model that can’t read their blocks drops it.
1109* **Claude Opus 5.5:** It reads thinking blocks from Claude Opus 5 and from earlier Opus, Sonnet, and Haiku models. On the Claude API and Claude Models on Google Cloud (Google managed), it also reads them from Claude Sonnet 5.5 and Claude Haiku 5.5. It doesn’t read them from the Claude Fable and Claude Mythos models. On the Claude API, Claude Fable 5.1 and Claude Mythos 5.1 read Claude Opus 5.5’s blocks. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 also read them. A switch from Claude Opus 5.5 up to Claude Fable 5.1 on the Claude API keeps the earlier turns’ reasoning. A switch from Claude Fable 5.1 to Claude Opus 5.5 drops it.
1110* **Claude Sonnet 5.5:** It reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models. On the Claude API and Claude Models on Google Cloud (Google managed), it also reads them from Claude Haiku 5.5. It doesn’t read them from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. On those two platforms, Claude Opus 5.5, Claude Fable 5.2, and Claude Mythos 5.2 read Claude Sonnet 5.5’s blocks. No other model does. A switch from Claude Sonnet 5.5 up to one of those three models there keeps the earlier turns’ reasoning. Any other switch away from Claude Sonnet 5.5 drops it.
1111* **Claude Haiku 5.5:** It reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models. It doesn’t read them from Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, or any Claude Fable or Claude Mythos model. Four models read Claude Haiku 5.5’s blocks: Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, and Claude Mythos 5.2. They do so on the Claude API and Claude Models on Google Cloud (Google managed). No other model does.
1108* **Claude Fable 5.1 and Claude Mythos 5.1:** They read each other’s thinking blocks and those of [earlier models](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#which-model-switches-keep-reasoning), except Claude Mythos Preview’s. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 also read their blocks. No other model does. A switch to Claude Fable 5.1 or Claude Mythos 5.1 from a model whose blocks they read keeps the conversation’s reasoning. A switch from either to a model that can’t read their blocks drops it.
1109* **Claude Opus 5.5:** It reads thinking blocks from Claude Opus 5 and from [earlier Claude Opus, Claude Sonnet, and Claude Haiku models](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#earlier-models). On the Claude API and Claude Models on Google Cloud (Google managed), it also reads them from Claude Sonnet 5.5 and Claude Haiku 5.5. It doesn’t read them from the Claude Fable and Claude Mythos models. On the Claude API, Claude Fable 5.1 and Claude Mythos 5.1 read Claude Opus 5.5’s blocks. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 also read them. A switch from Claude Opus 5.5 up to Claude Fable 5.1 on the Claude API keeps the earlier turns’ reasoning. A switch from Claude Fable 5.1 to Claude Opus 5.5 drops it.
1110* **Claude Sonnet 5.5:** It reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and [earlier Claude Opus, Claude Sonnet, and Claude Haiku models](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#earlier-models). On the Claude API and Claude Models on Google Cloud (Google managed), it also reads them from Claude Haiku 5.5. It doesn’t read them from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. On those two platforms, Claude Opus 5.5, Claude Fable 5.2, and Claude Mythos 5.2 read Claude Sonnet 5.5’s blocks. No other model does. A switch from Claude Sonnet 5.5 up to one of those three models there keeps the earlier turns’ reasoning. Any other switch away from Claude Sonnet 5.5 drops it.
1111* **Claude Haiku 5.5:** It reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and [earlier Claude Opus, Claude Sonnet, and Claude Haiku models](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#earlier-models). It doesn’t read them from Claude Opus 5, Claude Opus 5.5, Claude Sonnet 5.5, or any Claude Fable or Claude Mythos model. Four models read Claude Haiku 5.5’s blocks: Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, and Claude Mythos 5.2. They do so on the Claude API and Claude Models on Google Cloud (Google managed). No other model does.
11121112
1113Strip prior `thinking` and `redacted_thinking` blocks yourself only to save input tokens on models that ignore rather than drop them. Never strip them when redeeming a [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit), which requires the body unchanged.
1113Don’t strip thinking blocks when you switch. The API drops unreadable ones without billing them, and a model that reads them still gets them. Stripping also loses [fallback credit](https://platform.claude.com/docs/en/build-with-claude/fallback-credit), which requires the body unchanged.
11141114
11151115## Preserved thinking
11161116
1117[Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) determines whether the model can use a thinking block that you send back from an earlier turn. The API checks the `signature` of every `thinking` or `redacted_thinking` block in a request for two things:
1117On [models with preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#outcomes), each request that sends thinking blocks back gets a [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check). If your code changes `system`, `tools`, or an earlier message, every thinking block that already follows the change fails the prefix check. Then the request can get a 400 error.
11181118
1119* **The model that produced it.** Each model reads its own thinking blocks and those of a fixed set of other models. Claude Fable 5.1 reads blocks from Claude Opus 5 and, on the Claude API, from Claude Opus 5.5; neither Claude Opus 5 nor Claude Opus 5.5 reads blocks from Claude Fable 5.1. The API drops a block the current model can’t read, without an error and without billing it. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
1120* **Everything sent before it.** A block stays valid only while the top-level `system` prompt, the `tools`, and the messages before it are unchanged. If any of them changes, that block and every later thinking block already in the history fail the prefix check. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check).
1119Two other rules drop blocks, with no error. A model reads only some other models’ thinking blocks (see [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models)). And blocks from some models work only in the account that produced them, or in one linked to it (see [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking)).
11211120
1122Thinking blocks from Claude Sonnet 5.5, Claude Haiku 5.5, Claude Fable 5.2, and Claude Mythos 5.2 are also tied to the account that produced them. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking) for where this applies.
1121The models with preserved thinking are Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5.
11231122
1124The prefix check runs on Claude Fable 5.2, Claude Mythos 5.2, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5. Make your integration append-only so that the thinking blocks you send back pass it. [What the API does with an invalid block](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#mismatch-behavior) covers what happens when one fails.
1123For what counts as a change and what to send instead, see [Prefix checks on thinking blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks). If a request failed with “The block is bound to a different conversation”, go to [Fix a thinking block bound to a different conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/fix-bound-to-a-different-conversation).
11251124
1126To keep thinking valid, send every assistant turn back exactly as you received it and add new messages only at the end of `messages`. If your code builds the `messages` array itself, the Preserved thinking page covers:
1127
1128* [What counts as an edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#what-counts-as-an-edit), and [how to check whether your code makes an edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted).
1129* The [API feature that replaces each common edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#replace-prefix-edits): mid-conversation system messages for new instructions and per-turn reminders, `tool_addition` and `tool_removal` blocks for tool changes, per-message `output_config` for effort changes, and server-side compaction and context editing for trimming.
1130* [Client-side compaction](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#custom-compaction-on-the-client): which patterns keep thinking valid and which don’t.
1131* The [`thinking-binding-controls-2026-08-01` beta header](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#preserved-thinking-controls). It adds a `block_binding.prefix_mismatch_behavior` field (`"error"` or `"drop_block"`) to the thinking configuration and an `input_transformations` array to every response. The array lists each thinking block that the API dropped or that failed the prefix check and reached the model.
1132
11331125## Thinking and prompt caching
11341126
11351127[Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) interacts with thinking in a few specific ways. The following rules apply in both thinking modes.
11361128
1137**Configuration changes invalidate caching.** The thinking configuration and the resolved [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) level are rendered into the prompt itself, so changing any of them starts a new cache prefix. Switching between `adaptive`, `enabled`, and `disabled`, changing `budget_tokens`, and changing the effort value all invalidate cache breakpoints: message-level breakpoints always miss, and tool and system-prompt breakpoints can miss too, depending on where the model renders the configuration. Treat any thinking or top-level effort change as starting the cache over. On models that support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message), an effort change carried in a `role: "system"` message inside `messages` leaves the cached prefix intact. Consecutive requests that keep the same configuration preserve the cache, and setting a parameter explicitly to its default value is equivalent to omitting it. A thinking block the API drops under any [preserved-thinking condition](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking) changes the cached prefix from that block’s position onward. Blocks passed back unchanged keep the cache intact. A worked demonstration with usage output is on the [Steering thinking](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#prompt-caching) page.
1129**Configuration changes can invalidate caching.** The thinking configuration and the resolved [`effort`](https://platform.claude.com/docs/en/build-with-claude/effort) level are rendered into the prompt itself, so changing any of them changes the prompt.
11381130
1131Switching between `adaptive`, `enabled`, and `disabled`, or changing `budget_tokens`, invalidates cache breakpoints. Message-level breakpoints always miss, and tool and system-prompt breakpoints can miss too, depending on where the model renders the configuration. Changing the effort value can invalidate message-level breakpoints on any model. On Claude Opus 5, Claude Sonnet 5, Claude Fable 5, Claude Mythos 5, and earlier models that support effort, changing the effort value can invalidate tool and system-prompt breakpoints too. Treat any thinking or top-level effort change as invalidating the whole cache.
1132
1133On models that support [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message), an effort change carried in a `role: "system"` message inside `messages` leaves the cached prefix intact. Consecutive requests that keep the same configuration preserve the cache, and setting a parameter explicitly to its default value is equivalent to omitting it.
1134
1135A thinking block the API drops under any [preserved-thinking condition](https://platform.claude.com/docs/en/build-with-claude/thinking#preserved-thinking) changes the cached prefix from that block’s position onward. Blocks passed back unchanged keep the cache intact.
1136
11391137**Thinking blocks are cached with tool results.** During a tool-use loop, caching occurs when you make a follow-up request that includes tool results. At that point the previous conversation history, including its thinking blocks, can be cached, and those cached thinking blocks count as input tokens in your usage metrics when read from the cache. This occurs automatically, even without explicit `cache_control` markers, and behaves the same for regular and interleaved thinking. The tradeoff: thinking blocks you never see again in responses still contribute to input token usage when read from cache.
11401138
11411139**Whether prior blocks are in context at all is per-model.** The [preservation default](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model) governs this. On keep-all models, previous turns’ thinking blocks stay cached and in context. On last-turn-only models, once you send a user message that isn’t a tool result, all previous thinking blocks are stripped from context. On those models, a conversation like this:
from line 1198
12001198
12011199Keep the following in mind when working with signatures:
12021200
1203* It is only strictly necessary to send back thinking blocks when [using tools with thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use). Otherwise you can omit thinking blocks from previous turns. If you do pass them back, whether the API keeps or strips them depends on the model (see [Thinking block preservation by model](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model)). Use [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) to configure this.
1201* It is only strictly necessary to send back thinking blocks when [using tools with thinking](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use). Otherwise you can omit thinking blocks from previous turns, but not a block between two that you keep. If you do pass them back, whether the API keeps or strips them depends on the model (see [Thinking block preservation by model](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-block-preservation-by-model)). Use [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) to configure this.
12041202* When sending back thinking blocks, pass everything back exactly as you received it, for consistency and to avoid potential issues.
12051203* When [streaming responses](https://platform.claude.com/docs/en/build-with-claude/thinking#streaming-thinking), the signature arrives as a `signature_delta` inside a `content_block_delta` event just before the `content_block_stop` event.
12061204* `signature` values are significantly longer in Claude 4 and later models than in previous models.
12071205* The `signature` field is opaque: don’t interpret or parse it.
1208* `signature` values are compatible across platforms, including the Claude API, [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), and [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed). Values generated on one platform work on another, except that thinking blocks from Claude Sonnet 5.5, Claude Haiku 5.5, Claude Fable 5.2, and Claude Mythos 5.2 work only in the account that produced them or in an account linked to it. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
1206* `signature` values are compatible across platforms, including the Claude API, [Amazon Bedrock (`bedrock-mantle`)](https://platform.claude.com/docs/en/build-with-claude/claude-in-amazon-bedrock), and [Claude Models on Google Cloud (Google managed)](https://platform.claude.com/docs/en/build-with-claude/claude-models-on-google-cloud/google-managed). Values generated on one platform work on another, except that thinking blocks from Claude Sonnet 5.5, Claude Haiku 5.5, Claude Fable 5.2, and Claude Mythos 5.2 work only in the account that produced them or in an account linked to it. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
12091207
12101208## Redacted thinking blocks
12111209
from line 1218
12201218
12211219The `data` field is opaque and encrypted. As with the `signature` field on regular thinking blocks, pass `redacted_thinking` blocks back to the API unchanged when continuing a multi-turn conversation with [tools](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use).
12221220
1223<Tip>
1224 If your code filters content blocks by type (for example, `block.type == "thinking"`) when round-tripping responses with tool use, also include `redacted_thinking` blocks. Filtering on `block.type == "thinking"` alone silently drops `redacted_thinking` blocks and breaks the multi-turn protocol described in [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).
1225</Tip>
1221If your code filters content blocks by type (for example, `block.type == "thinking"`) when round-tripping responses with tool use, also include `redacted_thinking` blocks. Filtering on `block.type == "thinking"` alone silently drops `redacted_thinking` blocks and breaks the multi-turn protocol described in [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).
12261222
1227<Note>
1228 `redacted_thinking` blocks are a distinct content block type returned when thinking is safety-redacted. This is separate from the [`display: "omitted"`](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) option, which returns regular `thinking` blocks with an empty `thinking` field.
1229</Note>
1223`redacted_thinking` blocks are a distinct content block type returned when thinking is safety-redacted. This is separate from the [`display: "omitted"`](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) option, which returns regular `thinking` blocks with an empty `thinking` field.
12301224
12311225## Limits and feature compatibility
12321226
build-with-claude/thinking-steering-and-cost Changed · +5 / -5 lines
from line 120
120120* You can resume a conversation that started without thinking, or that used a different thinking configuration, without rewriting its history.
121121* History assembled from mixed sources doesn’t need thinking blocks reinserted at the start of each assistant turn to pass validation.
122122
123This rule is about validation, not about what you should send. When you have thinking blocks, pass them back unmodified, particularly during tool use, where they carry the reasoning behind Claude’s tool calls. See the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) overview for the full rules.
123This only means a turn can start without a thinking block. When you have thinking blocks, pass them back unmodified, particularly during tool use, where they carry the reasoning behind Claude’s tool calls. See the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) overview for the full rules.
124124
125125### Prompt caching
126126
127Consecutive requests that keep the same thinking configuration and effort level preserve prompt caching; see [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching) for the full rules. The resolved effort value is rendered into the prompt, so changing it between requests invalidates cache breakpoints, just as changing the legacy [`budget_tokens`](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#extended-thinking-with-prompt-caching) parameter does on models that use it. Setting `effort` explicitly to the model’s default is equivalent to omitting it and does not break the cache.
127Consecutive requests that keep the same thinking configuration and effort level preserve prompt caching; see [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching) for the full rules. The resolved effort value is rendered into the prompt, so changing it between requests can invalidate cache breakpoints. So can changing the legacy [`budget_tokens`](https://platform.claude.com/docs/en/build-with-claude/extended-thinking#extended-thinking-with-prompt-caching) parameter, on [models that use it](https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting#supported-models). Setting `effort` explicitly to the model’s default is equivalent to omitting it and does not break the cache.
128128
129The practical consequence: pick a thinking configuration and a top-level effort level for each conversation and keep them. If some turns need more or less thinking, use a [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) change, which is in beta, on models that support it, or steer with [per-message prompting](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#tuning-thinking-behavior). Both leave earlier cache breakpoints intact, where a change to the thinking configuration or the top-level effort level does not.
129The practical consequence: pick a thinking configuration and a top-level effort level for each conversation and keep them. If some turns need more or less thinking, use a [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) change, which is in beta, on [models that support it](https://platform.claude.com/docs/en/build-with-claude/effort-per-message#feature-availability). Or steer with [per-message prompting](https://platform.claude.com/docs/en/build-with-claude/thinking-steering-and-cost#per-message-steering). Both leave earlier cache breakpoints intact, where a change to the thinking configuration or the top-level effort level might not.
130130
131131The following example demonstrates the invalidation with a multi-turn script you can run yourself:
132132
133<Accordion title="Effort changes invalidate the prompt cache">
133<Accordion title="Effort changes can invalidate the prompt cache">
134134 <CodeGroup exclude="shell:cURL, shell:CLI">
135135 <CodeGroupItem language="cURL">
136136 This workflow needs more logic than a single shell command. Use the Anthropic SDK to run it; per-turn HTTP requests follow the examples on the [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) page.
build-with-claude/thinking-tool-workflows Changed · +7 / -7 lines
from line 8
88 To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
99</Note>
1010
11This page walks through a complete two-turn tool-use round trip with thinking enabled: Claude thinks, requests a tool call, receives the result, and finishes its answer, with the thinking blocks handled correctly at every step. The full rules live on the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) page, in [Thinking with tool use](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use) and [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks); this page shows those rules applied in runnable code.
11This page walks through a complete two-turn tool-use round trip with thinking enabled. Claude thinks, requests a tool call, receives the result, and finishes its answer. At every step, your code handles the thinking blocks correctly. The full rules are on the Thinking page, in [Thinking with tool use](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use) and [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).
1212
1313## The rules this walkthrough applies
1414
15Each link leads to the full statement on the Thinking page:
15Each rule links to its full statement:
1616
1717* [Limit tool choice to `auto` or `none` in manual mode](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-with-tool-use): with manual extended thinking (`thinking: {type: "enabled"}`), `tool_choice` options that force tool use return an error.
1818
from line 25
2525
2626* [Pass thinking blocks back complete and unmodified](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks): when you return a tool result, the thinking blocks from the assistant message must come back with it.
2727
28* [Echo the assistant message exactly as received](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks): rebuilding the message or filtering out `redacted_thinking` blocks triggers a 400 error.
28* [Echo the assistant message exactly as received](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks): dropping thinking blocks loses the reasoning in them, even without an error.
2929
30The samples use adaptive thinking; on models that support only extended thinking, substitute `thinking: {type: "enabled", budget_tokens: N}`. The round-trip rules are identical.
30The samples use adaptive thinking. On Claude Opus 4.5, Claude Sonnet 4.5, Claude Haiku 4.5, and earlier Claude 4 models, substitute `thinking: {type: "enabled", budget_tokens: N}`. Echo the assistant turn the same way.
3131
3232## Walk through a two-turn tool-use round trip
3333
34The example defines a `get_weather` tool, lets Claude think and request a tool call, then returns the tool result along with the assistant turn echoed exactly as received, thinking block included.
34The example defines a `get_weather` tool, lets Claude think and request a tool call, then returns the tool result with the assistant turn echoed exactly as received, thinking block included.
3535
3636<Steps>
3737 <Step title="Make the first request with a tool available">
from line 836
836836 </Card>
837837
838838 <Card title="Extended thinking" icon="clock" href="https://platform.claude.com/docs/en/build-with-claude/extended-thinking">
839 Manual thinking budgets on older models: `budget_tokens` mechanics and migration to adaptive.
839 Manual thinking budgets: `budget_tokens` mechanics and migration to adaptive thinking.
840840 </Card>
841841</CardGroup>
842842
build-with-claude/thinking-troubleshooting Changed · +19 / -17 lines
from line 1
11---
22title: Troubleshooting thinking
33url: https://platform.claude.com/docs/en/build-with-claude/thinking-troubleshooting
4description: "Diagnose and fix the most common thinking failures: configuration 400 errors, empty or missing thinking blocks, max_tokens stops, and cache misses."
4description: "Diagnose and fix thinking failures: configuration 400 errors, empty or missing thinking blocks, max_tokens stops, and cache misses."
55---
66
77<Note>
from line 8
88 To learn how zero data retention (ZDR) applies to this feature, see [API and data retention](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention).
99</Note>
1010
11This page covers the most common failures when configuring thinking or round-tripping thinking blocks (sending returned thinking blocks back in later requests). The first section maps each model to its supported thinking configurations and the ones it rejects; the sections after it each start from a symptom you observe, so you can match an error message or unexpected response directly to its cause and fix. To learn how thinking works, see the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) overview.
11This page covers failures when configuring thinking or round-tripping thinking blocks (sending returned thinking blocks back in later requests). The first section maps each model to its supported thinking configurations and the ones it rejects. Each later section starts from a symptom you observe, so you can match an error message or unexpected response directly to its cause and fix. To learn how thinking works, see the [Thinking](https://platform.claude.com/docs/en/build-with-claude/thinking) overview.
1212
1313## Thinking support, defaults, and rejected configurations by model
1414
from line 108
108108output_config.effort 'xhigh' is not supported when thinking is disabled on this model. Use effort 'high' or below, or enable thinking.
109109```
110110
111This occurs because Claude Sonnet 5.5 accepts `between_tools` only at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. The message says thinking is disabled because `between_tools` has no up-front thinking, even though the request didn’t send `"disabled"`. The message names the level the request sent.
111This occurs because Claude Sonnet 5.5 accepts `between_tools` only at [effort](https://platform.claude.com/docs/en/build-with-claude/effort) `high` or below. The error message says thinking is disabled because `between_tools` has no up-front thinking, even though the request didn’t send `"disabled"`. The message names the level the request sent.
112112
113113Lower the effort to `high` or below. To run at `xhigh` or `max`, use adaptive thinking: omit the `thinking` field or send `thinking: {"type": "adaptive"}`. That’s what the message means by “enable thinking.” Claude Sonnet 5.5 rejects `"enabled"` with a 400 error.
114114
from line 122
122122messages.N: output_config.effort 'low' differs from the 'high' in effect before it; effort cannot change when thinking is disabled on this model. Use effort 'high', or enable thinking.
123123```
124124
125The message says thinking is disabled because `between_tools` has no up-front thinking. With `between_tools`, effort can’t change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. `messages.N` is the position of the message that set the new level.
125The error message says thinking is disabled because `between_tools` has no up-front thinking. With `between_tools`, effort can’t change mid-conversation: a per-message `output_config.effort` that differs from the level in effect returns a 400 error. `messages.N` is the position of the message that set the new level.
126126
127127Remove that per-message effort, or set it to the level in effect. To vary effort for each turn, use adaptive thinking: omit the `thinking` field or send `thinking: {"type": "adaptive"}`. That’s what the message means by “enable thinking.”
128128
from line 148
148148`thinking` or `redacted_thinking` blocks in the latest assistant message cannot be modified
149149```
150150
151In multi-turn and tool-use conversations, you send previous assistant messages back to the API, including their `thinking` and `redacted_thinking` blocks. The API verifies that they arrive unmodified. This error occurs when the assistant message you send back differs from the one the API returned. The most common causes are code that filters content blocks by type and drops `redacted_thinking` blocks, and code that rebuilds the assistant message instead of echoing it.
151In multi-turn and tool-use conversations, you send previous assistant messages back to the API, including their `thinking` and `redacted_thinking` blocks. The API verifies their signatures.
152152
153This error can mean that thinking blocks in the request don’t match what the API returned. The mismatch can be in any assistant turn, although the error message says “latest.”
154
153155Echo the assistant turn back verbatim, thinking blocks included. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks) for the rules, and the worked round trip in [Thinking in tool and multi-turn workflows](https://platform.claude.com/docs/en/build-with-claude/thinking-tool-workflows#two-turn-tool-use-round-trip) for correct code in every SDK.
154156
155157## A 400 error says a thinking block signature is invalid
from line 162
160162messages.{i}.content.{j}: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block".
161163```
162164
163If the request didn’t send the `thinking-binding-controls-2026-08-01` beta header, the message adds ``That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.``
165If the request didn’t send the `thinking-binding-controls-2026-08-01` beta header, the error message adds ``That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.``
164166
165The message usually ends with a sentence naming what changed: the `system` prompt, the `tools` list, the first message or block that differs, content that is missing or new, or an earlier thinking block that is missing or out of order. That sentence is for people and logs. Its wording can change, so don’t match on it in code.
167The error message can end with a sentence naming what changed: the `system` prompt, the `tools` list, the first message or block that differs, content that is missing or new, or an earlier thinking block that is missing or out of order. That sentence is for people and logs. Its wording can change, so don’t match on it in code.
166168
167If the message stops after ``Invalid `signature` in `thinking` block``, the signature itself didn’t verify: it was truncated, altered, or sent back empty, and `prefix_mismatch_behavior` doesn’t apply.
169If the error message stops after ``Invalid `signature` in `thinking` block``, the signature itself didn’t verify: it was truncated, altered, or sent back empty, and `prefix_mismatch_behavior` doesn’t apply.
168170
169A replayed thinking block passes the prefix check only while the `system` prompt, `tools`, and messages that preceded it are unchanged. See [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check). The error means something earlier in the conversation changed between requests. Common causes include the following:
171A replayed thinking block passes the prefix check only while the `system` prompt, `tools`, and messages that preceded it are unchanged. See [What must stay the same, and why](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check). The error means something earlier in the conversation changed between requests. Causes include the following:
170172
171173* An edited, reordered, or removed turn
172174* A per-turn reminder that was injected and later removed
from line 175
173175* A rebuilt `system` prompt or `tools` array
174176* Client-side compaction that kept recent turns and their thinking verbatim
175177
176Server-side [compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold) and [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) never trigger this error. With [on-demand compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand), thinking in the turns you keep after the summary triggers it when one of the [conditions for kept thinking](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#conditions-for-kept-thinking-to-stay-valid) doesn’t hold. For requests that don’t set `thinking.block_binding.prefix_mismatch_behavior`, see [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement).
178Server-side [compaction at a token threshold](https://platform.claude.com/docs/en/build-with-claude/compaction-threshold) and [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing) never trigger this error. With [on-demand compaction](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand), thinking in the turns you keep after the summary triggers it when one of the [conditions for kept thinking](https://platform.claude.com/docs/en/build-with-claude/compaction-thinking-blocks#conditions-for-kept-thinking-to-stay-valid) doesn’t hold. For requests that don’t set `thinking.block_binding.prefix_mismatch_behavior`, see [Which models run the prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#enforcement).
177179
178Retrying the same request body doesn’t clear the error. Neither does fixing your code, if the stored history holds the edit. To continue the conversation, do one of the following:
180Retrying the same request body doesn’t clear the error. Neither does fixing your code if the stored history holds the edit. To continue the conversation, do one of the following:
179181
180182* Send the `thinking-binding-controls-2026-08-01` beta header and set `thinking.block_binding.prefix_mismatch_behavior` to `"drop_block"` on the retry and every later request. The request then succeeds without the invalidated reasoning. On Claude Sonnet 5.5 and Claude Haiku 5.5, `block_binding` works only with `thinking: {"type": "adaptive"}`. With any other thinking setting on those models, you can’t send `block_binding`, so use the next option.
181183* Strip the block the error names and every later `thinking` and `redacted_thinking` block, leaving each turn’s other blocks in place. Retry, and leave the stripped blocks out of later requests.
from line 194
192194
193195Set `display: "summarized"` in your thinking configuration to receive the summarized thinking text. See [Controlling thinking display](https://platform.claude.com/docs/en/build-with-claude/thinking#controlling-thinking-display) for each model’s default. If you only want the short status lines some models write between tool calls, and not the reasoning, set `display: "updates"`, which is in beta, instead. See [Progress updates between tool calls](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates).
194196
195A block whose `thinking` field is empty is still complete: the `signature` holds the reasoning. Send it back with the turn like any other. See [Send assistant turns back exactly as returned](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#append-assistant-turns-exactly-as-returned).
197A block whose `thinking` field is empty is still complete: the `signature` holds the reasoning. Send it back with the turn like any other. See [Send assistant turns back exactly](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/change-tools-or-instructions#append-assistant-turns-exactly-as-returned).
196198
197199## No thinking block appears on some turns
198200
from line 226
224226
225227`cache_read_input_tokens` falls to zero on requests that previously hit the cache.
226228
227This occurs because the thinking configuration and the effort level (or its default) are part of the cached prompt prefix, so changing any of them starts a new prefix. Switching thinking modes, changing the effort value, and changing `budget_tokens` all invalidate message cache breakpoints. They can invalidate tool and system-prompt breakpoints too, depending on where the model renders the configuration.
229This occurs because the thinking configuration and the effort level (or its default) are part of the cached prompt prefix, so changing any of them starts a new prefix. Switching thinking modes and changing `budget_tokens` invalidate message cache breakpoints, and changing the effort value can. They can invalidate tool and system-prompt breakpoints too, depending on where the model renders the configuration.
228230
229231Keep the thinking configuration and effort level constant across requests that share a conversation; setting a parameter explicitly to its default is equivalent to omitting it and does not invalidate. See [Thinking and prompt caching](https://platform.claude.com/docs/en/build-with-claude/thinking#thinking-and-prompt-caching).
230232
manage-claude/compliance-security-posture/overview Changed · +6 / -2 lines
from line 12
1212
1313## Choose your path
1414
15To get changes on the page into your security information and event management (SIEM) system, start with [Send Security posture events to your SIEM](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/send-events). If you already ingest the whole Activity Feed, you have them; [check two things](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/send-events#if-you-already-ingest-the-full-feed).
15To get changes on the page into your security information and event management (SIEM) system, start with [Send Security posture events to your SIEM](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/send-events). If you already ingest the whole Activity Feed, you have them; check two things in the [If you already ingest the full feed](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/send-events#if-you-already-ingest-the-full-feed) section.
1616
1717* To alert on risky changes, see [Detect changes in Security posture](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/detect-changes).
1818* To normalize to the Open Cybersecurity Schema Framework (OCSF), see [Map Security posture events to OCSF](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/ocsf-mapping).
from line 117
117117
118118[Customer-managed encryption keys (CMEK)](https://platform.claude.com/docs/en/manage-claude/cmek), [zero data retention (ZDR) for Claude Code](https://code.claude.com/docs/en/zero-data-retention), and a [HIPAA-ready Enterprise plan](https://support.claude.com/en/articles/13296973-hipaa-ready-enterprise-plans) do not change what Anthropic stores of an attestation’s control, value, dates, and account. None of the three shortens how long Anthropic stores them. CMEK does not encrypt these fields.
119119
120Anthropic stores an attestation’s comment until someone clears the attestation or Anthropic deletes the comment with the organization. Attesting again can replace or remove the comment. While Security posture is not available to an organization, Anthropic keeps storing its attestations and comments, and nobody can see or clear them on the Security posture page. A custom conversation retention period does not shorten how long Anthropic stores the attestation or the comment. Activity Feed activities never include the comment (see [What the feed does not record](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/events-reference#what-the-feed-does-not-record)).
120An attestation’s comment is the answer to the question that the Security posture page can ask when someone attests. Anthropic stores an attestation’s comment until someone clears the attestation or Anthropic deletes the comment with the organization. Attesting again can replace or remove the comment. A custom conversation retention period does not shorten how long Anthropic stores the attestation or the comment. Activity Feed activities never include the comment (see [What the feed does not record](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/events-reference#what-the-feed-does-not-record)).
121
122Some organizations cannot save a comment with an attestation because of their data-handling settings, such as CMEK or ZDR. For those organizations, the Security posture page shows no comment box and asks for no answer when someone attests. If an organization saved a comment before those settings applied to it, the comment stays stored with its attestation. The Security posture page does not show that comment. Clearing the attestation deletes that comment.
123
124While Security posture is not available to an organization, Anthropic keeps storing its attestations and comments. In that time, nobody can see or clear them on the Security posture page.
121125
manage-claude/compliance-security-posture/results-reference Changed · +15 / -15 lines
from line 8
88 To enable the Compliance API, see [Set up the Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-api-access).
99</Note>
1010
11This endpoint returns an entry for most of an organization’s security controls, evaluated at the time of the request, with the [Security posture attestation](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/overview#attestations) that the response shows for each control. You need a Compliance Access Key that covers the organization, with the `read:compliance_org_data` or `read:org_audit` scope; [Security posture availability](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/overview#availability) says which organizations can be read.
11This endpoint returns an entry for most of an organization’s security controls, evaluated at the time of the request. Each entry’s `attestation` field holds the control’s [Security posture attestation](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/overview#attestations) or `null`. A `null` does not prove that nobody attested: [How an attestation shows in the response](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/results-reference#how-an-attestation-shows-in-the-response) lists which attestations the response shows. You need a Compliance Access Key that covers the organization, with the `read:compliance_org_data` or `read:org_audit` scope. [Security posture availability](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/overview#availability) says which organizations can be read.
1212
1313## Request
1414
from line 117
117117
118118### `controls[]` fields
119119
120| Field | Type | Description |
121| --------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
122| `id` | string | The control’s identifier, which is the same for every organization and never changes. |
123| `display_name` | string | The control’s display name, as English display text whose wording can change. |
124| `section` | string | The section that the control belongs to, one of the ten listed after this table; more values can be added, so treat an unknown one as a section of its own. |
125| `setting_name` | string or null | The `name` of the entry in the organization’s effective settings that this control reads; `null` when it reads no such entry. |
126| `status` | string | The reason for the control’s result; see [Status values](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/results-reference#status-values). |
127| `rating` | string | The control’s result, which follows from `status`; see [Status values](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/results-reference#status-values). |
128| `current_value` | string or null | The current value, as English display text whose wording can change; `null` on a manual control or when no value was read. |
129| `desired_state` | string or null | The recommended value, as English display text whose wording can change; `null` when there is none for this organization. |
130| `attestation` | object or null | The attestation that the response shows, also while it is not in effect; `null` while `status` is `descriptive`, `not_applicable`, or `not_evaluated`, and in [these cases](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/results-reference#how-an-attestation-shows-in-the-response). |
120| Field | Type | Description |
121| --------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
122| `id` | string | The control’s identifier, which is the same for every organization and never changes. |
123| `display_name` | string | The control’s display name, as English display text whose wording can change. |
124| `section` | string | The section that the control belongs to, one of the 10 listed after this table; more values can be added, so treat an unknown one as a section of its own. |
125| `setting_name` | string or null | The `name` of the entry in the organization’s effective settings that this control reads; `null` when it reads no such entry. |
126| `status` | string | The reason for the control’s result; see [Status values](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/results-reference#status-values). |
127| `rating` | string | The control’s result, which follows from `status`; see [Status values](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/results-reference#status-values). |
128| `current_value` | string or null | The current value, as English display text whose wording can change; `null` on a manual control or when no value was read. |
129| `desired_state` | string or null | The recommended value, as English display text whose wording can change; `null` when there is none for this organization. |
130| `attestation` | object or null | The attestation that the response shows, also while it is not in effect; `null` while `status` is `descriptive`, `not_applicable`, or `not_evaluated`, and in the cases under [How an attestation shows in the response](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/results-reference#how-an-attestation-shows-in-the-response). |
131131
132132`section` is one of `identity_access`, `data_privacy`, `capabilities`, `connectors_integrations`, `chats_desktop_mdm`, `cowork_admin_console`, `cowork_desktop_mdm`, `claude_code_admin_console`, `claude_code_managed_settings`, and `healthy_adoption`.
133133
from line 237
237237
238238## Errors
239239
240Errors use the same body as the rest of the [Compliance API](https://platform.claude.com/docs/en/manage-claude/compliance-errors); this table lists the ones that this endpoint returns in its own way.
240Errors use the same body as the rest of the Compliance API. [Handle Compliance API errors](https://platform.claude.com/docs/en/manage-claude/compliance-errors) describes that body. This table lists the errors that this endpoint returns in its own way.
241241
242242| Status and `error.type` | When | What to do |
243243| -------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
from line 244
244244| 400 `invalid_request_error` | `anthropic-version` is missing or invalid, the Compliance API is not enabled for the parent organization, or there is a query parameter. | Fix what `error.message` names. |
245245| 401 `authentication_error` | The key is missing, not recognized, or not a Compliance Access Key or Admin API key. | Send a valid Compliance Access Key in `x-api-key`. |
246246| 403 `permission_error` | The key may not call this endpoint, usually because it lacks both `read:compliance_org_data` and `read:org_audit`. | Use a key with either scope. |
247| 404 `not_found_error` | See the causes listed after this table. | Do not retry at once and never read it as no failed controls. |
247| 404 `not_found_error` | See the causes listed after this table. | Do not retry at once. A 404 does not mean that the organization has no failed controls. |
248248| 429 `rate_limit_error` | The shared Compliance API rate limit, or this endpoint’s lower limit, is used up; `error.message` says which. | Wait for `retry-after`; see [429 Too Many Requests](https://platform.claude.com/docs/en/manage-claude/compliance-errors#429-too-many-requests). |
249249| 503 `overloaded_error`, with `error.details.error_code` of `posture_evaluation_failed` | The result could not be produced. | Wait for `retry-after`, then retry; if it recurs for one organization on later runs, contact Anthropic support once. |
250250| 503 with no `error_code`, or 504 `timeout_error` | A temporary failure. | Retry with exponential backoff. |
from line 268
268268* A result can change with no setting changed, for example when an end date comes or Anthropic changes a recommended value.
269269* If Anthropic rewords a current value, an accepted risk on it is not in effect.
270270* A call stores no result and ends no attestation.
271* Each request that passes the key, scope, and version checks without a query parameter records one `compliance_api_accessed` activity, whether it succeeds or fails; its `url` names the organization read, and `organization_uuid` is `null` for a key for the parent organization.
271* A request with either a key for the parent organization or a key for a single organization on Claude Enterprise records one `compliance_api_accessed` activity. It does so when the request passes the key, scope, and version checks without a query parameter, whether it succeeds or fails. The activity’s `url` names the organization read, and `organization_uuid` is `null` for a key for the parent organization.
272272
managed-agents/environments Changed · +10 / -10 lines
## Preinstalled runtimes ## Pre-installed runtimes
from line 179
179179
180180## Use the environment in a session
181181
182Pass the environment ID as a string when [creating a session](https://platform.claude.com/docs/en/managed-agents/sessions).
182Pass the environment ID as a string when you create a session (see [Start a session](https://platform.claude.com/docs/en/managed-agents/sessions)).
183183
184184<CodeGroup>
185185 ```bash cURL
from line 258
258258
259259### Packages
260260
261The `packages` (csharp, go: `Packages`) field pre-installs packages into the sandbox before the agent starts. Packages are installed by their respective package managers and cached across sessions that share the same environment. When multiple package managers are specified, they run in alphabetical order (apt, cargo, gem, go, npm, pip). You can optionally pin specific versions. Unpinned packages install the latest version. If the environment uses `limited` [networking](https://platform.claude.com/docs/en/managed-agents/environments#networking), also set `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) in `networking` (csharp, go: `Networking`) to `true`; otherwise the request is rejected with a 400 error.
261The `packages` (csharp, go: `Packages`) field installs packages into the sandbox before the agent uses it. Package managers run in alphabetical order (apt, cargo, gem, go, npm, pip). You can pin specific versions. If the environment uses `limited` [networking](https://platform.claude.com/docs/en/managed-agents/environments#networking), also set `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) in `networking` (csharp, go: `Networking`) to `true`; otherwise, the API rejects the request with a 400 error.
262262
263263<CodeGroup defaultLanguage="CLI">
264264 ```bash cURL
from line 609
609609</CodeGroup>
610610
611611<Info>
612 Use `limited` networking with an explicit `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) list. Follow the principle of least privilege by granting only the minimum network access your agent requires, and regularly audit your allowed domains.
612 Use `limited` networking with an explicit `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) list. Follow the principle of least privilege by granting only the minimum network access your agent requires, and regularly audit your allowed hosts.
613613</Info>
614614
615615With `limited` networking and no other fields set, no hosts are allowed. Files, memory stores, and GitHub repositories that you attach to the session stay available. When a request from the sandbox on port 80 or 443 is refused because its host is not allowed, the response is a 403 that names the blocked host.
from line 616
616616
617617When using `limited` networking:
618618
619* `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) specifies domains the sandbox can reach. Specify bare hostnames or wildcard patterns (such as `*.example.com`). Do not include a URL scheme, port, or path. A bare hostname matches that exact host: `example.com` does not match `www.example.com`. `*.example.com` matches every subdomain of `example.com`, but not `example.com` itself.
619* `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) specifies hosts the sandbox can reach. Specify bare hostnames or wildcard patterns (such as `*.example.com`). Do not include a URL scheme, port, or path. A bare hostname matches that exact host: `example.com` does not match `www.example.com`. `*.example.com` matches every subdomain of `example.com`, but not `example.com` itself.
620620* `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) allows outbound access to MCP server endpoints configured on the agent, beyond those listed in the `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) array. Defaults to `false`. While it is `false`, session creation fails with a 400 error if the agent declares an MCP server whose host is not in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). The same applies to [an agent it can delegate to](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration). To fix it, add the host to `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) or set `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) to `true`.
621* `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) allows outbound access to a set of public package registries and code hosts beyond those listed in the `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) array. See [Package manager hosts](https://platform.claude.com/docs/en/managed-agents/environments#package-manager-hosts) for the list. Defaults to `false`. Set it to `true` whenever the environment specifies `packages` (csharp, go: `Packages`); otherwise the request is rejected with a 400 error, even if the registry hosts are listed in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`).
621* `allow_package_managers` (java, php: `allowPackageManagers`; csharp, go: `AllowPackageManagers`) allows outbound access to a set of public package registries and code hosts beyond those listed in the `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) array. See [Package manager hosts](https://platform.claude.com/docs/en/managed-agents/environments#package-manager-hosts) for the list. Defaults to `false`. Set it to `true` whenever the environment specifies `packages` (csharp, go: `Packages`). Otherwise, the API rejects the request with a 400 error, even if `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`) lists the registry hosts.
622622
623623#### Package manager hosts
624624
from line 669
669669
670670## Environment lifecycle
671671
672* Environments persist until explicitly archived or deleted.
672* Environments persist until you archive or delete them.
673673* Each session gets its own sandbox instance, even when multiple sessions reference the same environment. Sessions do not share filesystem state.
674674* Environments are not versioned. If you update an environment frequently, keep your own record of the changes so you can tell which configuration each session used.
675675
from line 812
812812 ```
813813</CodeGroup>
814814
815## Pre-installed runtimes
815## Preinstalled runtimes
816816
817Cloud sandboxes include common language runtimes, databases, and command-line tools out of the box. See [Cloud sandbox reference](https://platform.claude.com/docs/en/managed-agents/cloud-sandboxes-reference) for the full list.
817Cloud sandboxes include common language runtimes, databases, and command-line tools. See [Cloud sandbox reference](https://platform.claude.com/docs/en/managed-agents/cloud-sandboxes-reference) for the full list.
818818
819819## Next steps
820820
821821<CardGroup cols={2}>
822822 <Card title="Cloud sandbox reference" icon="book" href="https://platform.claude.com/docs/en/managed-agents/cloud-sandboxes-reference">
823 Pre-installed packages, databases, and utilities available in cloud sandboxes.
823 Preinstalled packages, databases, and utilities available in cloud sandboxes.
824824 </Card>
825825
826826 <Card title="Start a session" icon="play" href="https://platform.claude.com/docs/en/managed-agents/sessions">
managed-agents/mcp-connector Changed · +7 / -7 lines
from line 42
4242MCP configuration is split across two steps:
4343
44441. **Agent creation** declares which MCP servers the agent connects to, by name and URL.
452. **Session creation** supplies authentication for those servers by referencing a pre-registered vault (see [Authenticate with vaults](https://platform.claude.com/docs/en/managed-agents/vaults)).
452. **Session creation** supplies authentication for those servers by referencing a preregistered vault (see [Authenticate with vaults](https://platform.claude.com/docs/en/managed-agents/vaults)).
4646
4747This separation keeps secrets out of reusable agent definitions while letting each session authenticate with its own credentials.
4848
4949## Declare MCP servers on the agent
5050
51Specify MCP servers in the `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) array when creating an agent. Each server has a `type` (csharp, go: `Type`) of `url`, a unique `name` (csharp, go: `Name`), and a `url` (csharp: `Url`; go: `URL`). No authentication tokens are provided at this stage.
51Specify MCP servers in the `mcp_servers` (java, php: `mcpServers`; csharp: `McpServers`; go: `MCPServers`) array when creating an agent. Each server has a `type` (csharp, go: `Type`) of `url`, a unique `name` (csharp, go: `Name`), and a `url` (csharp: `Url`; go: `URL`). You don’t provide authentication tokens at this stage.
5252
5353Each declared server also needs a matching `mcp_toolset` entry in the `tools` (csharp, go: `Tools`) array. The toolset’s `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) must match the server’s `name` (csharp, go: `Name`).
5454
from line 260
260260
261261The `mcp_toolset` entry supports a `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) object and a `configs` (csharp, go: `Configs`) array, applied to the tools the MCP server exposes. Each `configs` (csharp, go: `Configs`) entry accepts only `name` (csharp, go: `Name`), `enabled` (csharp, go: `Enabled`), and `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). Unlike entries in the built-in agent toolset, MCP tool entries do not take a `type` (csharp, go: `Type`) field, and the [web settings](https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions#settings) available on `web_search` and `web_fetch` do not apply to MCP tools. The `name` (csharp, go: `Name`) in each `configs` (csharp, go: `Configs`) entry is the bare tool name as reported by the server.
262262
263By default all tools exposed by the MCP server are enabled. To enable only specific tools, set `default_config.enabled` to `false` and explicitly enable the tools you want:
263By default, all tools that the MCP server exposes are enabled. To enable only specific tools, set `default_config.enabled` (java, php: `defaultConfig.enabled`; csharp, go: `DefaultConfig.Enabled`) to `false` and explicitly enable the tools you want:
264264
265265```json
266266{
from line 277
277277
278278This pattern is useful when a server exposes many tools but the agent only needs a few, or when you want tools added by the server operator to stay off until you review them.
279279
280To disable specific tools while keeping the rest enabled, omit `default_config` and set `enabled: false` on individual entries:
280To disable specific tools while keeping the rest enabled, omit `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) and set `enabled: false` on individual entries:
281281
282282```json
283283{
from line 287
287287}
288288```
289289
290See [configuring the toolset](https://platform.claude.com/docs/en/managed-agents/tools#configuring-the-toolset) for the general `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`) pattern, and [MCP toolset permissions](https://platform.claude.com/docs/en/managed-agents/permission-policies#mcp-toolset-permissions) for setting `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) on MCP tools and handling confirmation requests.
290See [Configuring the toolset](https://platform.claude.com/docs/en/managed-agents/tools#configuring-the-toolset) for the general `default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`) / `configs` (csharp, go: `Configs`) pattern, and [MCP toolset permissions](https://platform.claude.com/docs/en/managed-agents/permission-policies#mcp-toolset-permissions) for setting `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) on MCP tools and handling confirmation requests.
291291
292292### MCP tool output handling
293293
from line 297
297297
298298When starting a session, pass `vault_ids` (java: `vaultIds`; php: `vaultIDs`; csharp: `VaultIds`; go: `VaultIDs`) to provide credentials for your MCP servers. Vaults are collections of credentials that you register once and reference by ID. See [Authenticate with vaults](https://platform.claude.com/docs/en/managed-agents/vaults) for how to create vaults and manage credentials.
299299
300With a `limited` [environment](https://platform.claude.com/docs/en/managed-agents/environments#networking), session creation fails with a 400 error when the agent declares an MCP server whose host is not in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Setting `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) to `true` in the environment’s networking turns this check off.
300With `limited` networking, session creation fails with a 400 error when the agent declares an MCP server whose host is not in `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). Setting `allow_mcp_servers` (java: `allowMcpServers`; php: `allowMCPServers`; csharp: `AllowMcpServers`; go: `AllowMCPServers`) to `true` in the environment’s networking turns this check off. See [Networking](https://platform.claude.com/docs/en/managed-agents/environments#networking) in Cloud environment setup.
301301
302302<CodeGroup>
303303 ```bash cURL
from line 387
387387
388388### Handle connection and authentication failures
389389
390Session creation does not validate MCP connectivity or credentials. It does check each declared server’s host against the environment’s networking: with a `limited` environment, session creation fails with a 400 error when a host is not allowed, as described under [Provide authentication at session creation](https://platform.claude.com/docs/en/managed-agents/mcp-connector#provide-authentication-at-session-creation). If an MCP server is unreachable or rejects the supplied credential, the session still starts and interaction remains possible. A [`session.error`](https://platform.claude.com/docs/en/managed-agents/reference#event-types) event is emitted with the `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) of the affected server and a `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`):
390Session creation does not validate MCP connectivity or credentials. It does check each declared server’s host against the environment’s networking. With `limited` networking, session creation fails with a 400 error when a host is not allowed, as described under [Provide authentication at session creation](https://platform.claude.com/docs/en/managed-agents/mcp-connector#provide-authentication-at-session-creation). If an MCP server is unreachable or rejects the supplied credential, the session still starts, and you can still interact with it. The session emits a [`session.error`](https://platform.claude.com/docs/en/managed-agents/reference#event-types) event with the `mcp_server_name` (java, php: `mcpServerName`; csharp: `McpServerName`; go: `MCPServerName`) of the affected server and a `retry_status` (java, php: `retryStatus`; csharp, go: `RetryStatus`):
391391
392392| Error type | Meaning |
393393| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
managed-agents/migration Changed · +38 / -22 lines
from line 45
4545
4646### What you stop managing
4747
48| Before | After |
49| ------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
50| You maintain the conversation history array and pass it back on every turn. | The session stores history server-side. You send events and receive events. |
51| You iterate `tool_use` content blocks, run each tool, and loop back with `tool_result` messages. | Pre-built tools run inside the sandbox automatically. You only handle custom tools through `agent.custom_tool_use` events. |
52| You provision your own sandbox for running agent-generated code. | The session sandbox handles code execution, file operations, and bash. |
53| You decide when the loop is done. | The session emits `session.status_idle` when the agent has nothing more to do. |
48| Before | After |
49| ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------- |
50| You maintain the conversation history array and pass it back on every turn. | The session stores history server-side. You send events and receive events. |
51| You iterate `tool_use` content blocks, run each tool, and loop back with `tool_result` messages. | Built-in tools run inside the sandbox automatically. You only handle custom tools through `agent.custom_tool_use` events. |
52| You provision your own sandbox for running agent-generated code. | The session sandbox handles code execution, file operations, and bash. |
53| You decide when the loop is done. | The session emits `session.status_idle` when the agent has nothing more to do. |
5454
5555### Code comparison
5656
from line 57
5757**Before** (Messages API loop, simplified):
5858
5959<CodeGroup exclude="shell:cURL, shell:CLI">
60 <CodeGroupItem language="cURL">
61 This loop needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
62 </CodeGroupItem>
63
64 <CodeGroupItem language="CLI">
65 This loop needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
66 </CodeGroupItem>
67
6068 ```python Python
6169 messages = [{"role": "user", "content": task}]
6270 while True:
from line 543
535543
536544### What changes
537545
538| Agent SDK | Managed Agents |
539| ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
540| `ClaudeAgentOptions(...)` (typescript: `options`) constructed per run | `client.beta.agents.create(...)` (csharp: `client.Beta.Agents.Create(...)`; go: `client.Beta.Agents.New(...)`; java: `client.beta().agents().create(...)`; php: `$client->beta->agents->create(...)`) once; the Agent is persisted and versioned server-side. See [Agent setup](https://platform.claude.com/docs/en/managed-agents/agent-setup). |
541| `async with ClaudeSDKClient(...)` or `query(...)` | `client.beta.sessions.create(...)` (csharp: `client.Beta.Sessions.Create(...)`; go: `client.Beta.Sessions.New(...)`; java: `client.beta().sessions().create(...)`; php: `$client->beta->sessions->create(...)`) then send and receive [events](https://platform.claude.com/docs/en/managed-agents/events-and-streaming). |
542| Functions defined with `@tool` (typescript: `tool()`), dispatched automatically by the SDK | Declare as `{"type": "custom", ...}` on the Agent; your client handles `agent.custom_tool_use` events and replies with `user.custom_tool_result`. See [Tools](https://platform.claude.com/docs/en/managed-agents/tools). |
543| Built-in tools run in your process against your filesystem | `{"type": "agent_toolset_20260401"}` runs the same tools inside the session sandbox against `/workspace`. |
544| `cwd`, `add_dirs` (typescript: `additionalDirectories`) point at local paths | Upload or mount [files](https://platform.claude.com/docs/en/managed-agents/files) as session resources. |
545| `system_prompt` (typescript: `systemPrompt`) and the `CLAUDE.md` hierarchy | A single `system` (csharp, go: `System`; ruby: `system_`) string on the Agent. Each update that changes the agent produces a new server-side version; pin sessions to a specific version to promote or roll back without a deploy. See [Agent setup](https://platform.claude.com/docs/en/managed-agents/agent-setup). |
546| `mcp_servers` (typescript: `mcpServers`) configured and authenticated in one place | Declare servers on the Agent; provide credentials through a [Vault](https://platform.claude.com/docs/en/managed-agents/vaults) on the Session. |
547| `permission_mode` (typescript: `permissionMode`), `can_use_tool` (typescript: `canUseTool`) | Per-tool [`permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)](https://platform.claude.com/docs/en/managed-agents/permission-policies) (`always_allow`, `always_ask`, or `auto`); send `user.tool_confirmation` events for calls that pause for your approval. |
546| Agent SDK | Managed Agents |
547| ------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
548| `ClaudeAgentOptions(...)` (typescript: `options`) constructed for each run | `client.beta.agents.create(...)` (csharp: `client.Beta.Agents.Create(...)`; go: `client.Beta.Agents.New(...)`; java: `client.beta().agents().create(...)`; php: `$client->beta->agents->create(...)`; cli: `ant beta:agents create`; curl: `POST /v1/agents`) once. The server persists and versions the agent. See [Define your agent](https://platform.claude.com/docs/en/managed-agents/agent-setup). |
549| `async with ClaudeSDKClient(...)` or `query(...)` | `client.beta.sessions.create(...)` (csharp: `client.Beta.Sessions.Create(...)`; go: `client.Beta.Sessions.New(...)`; java: `client.beta().sessions().create(...)`; php: `$client->beta->sessions->create(...)`; cli: `ant beta:sessions create`; curl: `POST /v1/sessions`) then send and receive [events](https://platform.claude.com/docs/en/managed-agents/events-and-streaming). |
550| Functions defined with `@tool` (typescript: `tool()`), dispatched automatically by the SDK | Declare as `{"type": "custom", ...}` on the agent; your client handles `agent.custom_tool_use` events and replies with `user.custom_tool_result`. See [Tools](https://platform.claude.com/docs/en/managed-agents/tools). |
551| Built-in tools run in your process against your filesystem | `{"type": "agent_toolset_20260401"}` runs the same tools inside the session sandbox against `/workspace`. |
552| `cwd`, `add_dirs` (typescript: `additionalDirectories`) point at local paths | Upload or mount [files](https://platform.claude.com/docs/en/managed-agents/files) as session resources. |
553| `system_prompt` (typescript: `systemPrompt`) and the `CLAUDE.md` hierarchy | A single `system` (csharp, go: `System`; ruby: `system_`) string on the agent. Each update that changes the agent produces a new server-side version; pin sessions to a specific version to promote or roll back without a deploy. See [Define your agent](https://platform.claude.com/docs/en/managed-agents/agent-setup). |
554| `mcp_servers` (typescript: `mcpServers`) configured and authenticated in one place | Declare servers on the agent; provide credentials through a [vault](https://platform.claude.com/docs/en/managed-agents/vaults) on the session. |
555| `permission_mode` (typescript: `permissionMode`), `can_use_tool` (typescript: `canUseTool`) | Per-tool [`permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`)](https://platform.claude.com/docs/en/managed-agents/permission-policies) (`always_allow`, `always_ask`, or `auto`); send `user.tool_confirmation` events for calls that pause for your approval. |
548556
549557### Code comparison
550558
from line 617
609617
610618**After** (Managed Agents):
611619
612<CodeGroup exclude="shell">
620<CodeGroup exclude="shell:cURL, shell:CLI">
621 <CodeGroupItem language="cURL">
622 This loop needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
623 </CodeGroupItem>
624
625 <CodeGroupItem language="CLI">
626 This loop needs more logic than a single shell command. Use the [Anthropic SDK](https://platform.claude.com/docs/en/cli-sdks-libraries/overview) to run it.
627 </CodeGroupItem>
628
613629 ```python Python
614630 from anthropic import Anthropic
615631
from line 1173
11571173 break;
11581174 case $event instanceof ManagedAgentsSessionStatusIdleEvent:
11591175 if ($event->stopReason instanceof ManagedAgentsSessionEndTurn) {
1160 break 2;
1176 break 2; // Leave the foreach loop
11611177 }
11621178 break;
11631179 }
from line 1248
12321248 ```
12331249</CodeGroup>
12341250
1235The Agent and Environment are created once and reused across sessions. The tool function still runs in your process; the difference is that you read the `agent.custom_tool_use` event and send the result explicitly instead of the SDK dispatching it for you.
1251You create the agent and environment once and reuse them across sessions. The tool function still runs in your process. The difference is that you read the `agent.custom_tool_use` event and send the result explicitly instead of the Agent SDK dispatching it for you.
12361252
12371253### Features that move to your client
12381254
from line 1368
13521368 ```
13531369</CodeGroup>
13541370
1355Most model-level behavior changes documented in the [Messages API migration guide](https://platform.claude.com/docs/en/about-claude/models/migration-guide) do not require action on your side:
1371Most model-level behavior changes documented in the [Migration guides](https://platform.claude.com/docs/en/about-claude/models/migration-guide) do not require action on your side:
13561372
13571373* **Request parameter changes** (`max_tokens` (java, php: `maxTokens`; csharp, go: `MaxTokens`) defaults, `thinking` (csharp, go: `Thinking`) configuration) are handled by the Claude Managed Agents runtime. These fields are not exposed on the agent definition.
1358* **Assistant message prefilling** does not exist in the event-based session model, so its removal on newer models is a no-op.
1374* **Assistant message prefilling** does not exist in the event-based session model, so moving to a model that rejects prefill needs no change from you.
13591375* **Tool argument JSON escaping** is parsed by the runtime before you receive `agent.custom_tool_use` events. You see structured data, not raw strings.
13601376
1361The behavior descriptions in the Messages API guide (what the model does differently) still apply. The migration steps (how to change your request code) do not.
1377The behavior descriptions in those guides (what the model does differently) still apply. The migration steps (how to change your request code) do not.
13621378
managed-agents/permission-policies Changed · +62 / -58 lines
from line 37
3737 Claude Models on Google Cloud (Anthropic managed): beta
3838---
3939
40Permission policies control whether server-executed tools (the pre-built agent toolset and MCP toolset) run automatically, wait for your approval, or have each call evaluated by the server. Custom tools are run by your application and controlled by you, so they are not governed by permission policies.
40Permission policies apply to server-executed tools: the prebuilt agent toolset and MCP toolsets. A policy determines whether a tool’s calls run automatically, wait for your approval, or go to the server, which evaluates each call. Custom tools run in your application, under your control, so permission policies don’t apply to custom tools.
4141
4242## Permission policy types
4343
from line 655
655655 ```
656656</CodeGroup>
657657
658Pass this `tools` (csharp, go: `Tools`) configuration in the agent create request (the CLI tab shows the complete command). MCP toolsets support the same per-tool overrides, with `name` (csharp, go: `Name`) set to the tool name reported by the MCP server. See [Configure which MCP tools are available](https://platform.claude.com/docs/en/managed-agents/mcp-connector#configure-which-mcp-tools-are-available).
658Pass this `tools` (csharp, go: `Tools`) configuration when you create the agent. MCP toolsets support the same per-tool overrides, with `name` (csharp, go: `Name`) set to the tool name reported by the MCP server. See [Configure which MCP tools are available](https://platform.claude.com/docs/en/managed-agents/mcp-connector#configure-which-mcp-tools-are-available).
659659
660660## Let the server evaluate each call with `auto`
661661
from line 665
665665* **The call is denied.** When the server evaluates the call as high-risk, the tool does not run. The agent receives an error tool result with the content `Permission to use {tool_name} has been denied.` and `is_error: true`. The session keeps running, and your client cannot override the denial.
666666* **The call pauses for your approval.** When the server reaches no determination, the session pauses as it does under `always_ask`. See [Respond to confirmation requests](https://platform.claude.com/docs/en/managed-agents/permission-policies#respond-to-confirmation-requests).
667667
668To turn on `auto`, set `permission_policy` to `{"type": "auto"}`. It goes in the same two places as the other policies: a toolset’s [`default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`)](https://platform.claude.com/docs/en/managed-agents/permission-policies#set-a-policy-for-a-toolset) for the whole toolset, or a [`configs` (csharp, go: `Configs`) entry](https://platform.claude.com/docs/en/managed-agents/permission-policies#override-an-individual-tool-policy) for one tool. The agent toolset and MCP toolsets both accept it. No toolset uses `auto` by default.
668To turn on `auto`, set `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`) to `{"type": "auto"}`. It goes in the same two places as the other policies: a toolset’s [`default_config` (java, php: `defaultConfig`; csharp, go: `DefaultConfig`)](https://platform.claude.com/docs/en/managed-agents/permission-policies#set-a-policy-for-a-toolset) for the whole toolset, or a [`configs` (csharp, go: `Configs`) entry](https://platform.claude.com/docs/en/managed-agents/permission-policies#override-an-individual-tool-policy) for one tool. The agent toolset and MCP toolsets both accept it. No toolset uses `auto` by default.
669669
670670The following example sets `auto` as the default for the agent toolset and for the `github` MCP toolset, and overrides `bash` to `always_ask`:
671671
from line 1069
10691069<CodeGroup>
10701070 ```bash cURL
10711071 # Allow the tool to run
1072 curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
1072 curl -fsSL https://api.anthropic.com/v1/sessions/sesn_011CZkZAtmR3yMPDzynEDxu7/events \
10731073 -H "x-api-key: $ANTHROPIC_API_KEY" \
10741074 -H "anthropic-version: 2026-10-21" \
10751075 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 1078
10781078 "events": [
10791079 {
10801080 "type": "user.tool_confirmation",
1081 "tool_use_id": "'$AGENT_TOOL_USE_EVENT_ID'",
1081 "tool_use_id": "sevt_011CZkZbMpR8aS3Wtv5Yq2Ln",
10821082 "result": "allow"
10831083 }
10841084 ]
10851085 }'
10861086
1087 # Or deny it with an explanation
1088 curl -fsSL "https://api.anthropic.com/v1/sessions/$SESSION_ID/events" \
1087 # Deny another call with an explanation
1088 curl -fsSL https://api.anthropic.com/v1/sessions/sesn_011CZkZAtmR3yMPDzynEDxu7/events \
10891089 -H "x-api-key: $ANTHROPIC_API_KEY" \
10901090 -H "anthropic-version: 2026-10-21" \
10911091 -H "anthropic-beta: managed-agents-2026-04-01" \
from line 1094
10941094 "events": [
10951095 {
10961096 "type": "user.tool_confirmation",
1097 "tool_use_id": "'$MCP_TOOL_USE_EVENT_ID'",
1097 "tool_use_id": "sevt_011CZkZcNqT9bT4Xuw6Zr3Mo",
10981098 "result": "deny",
1099 "deny_message": "Don'\''t create issues in the production project. Use the staging project."
1099 "deny_message": "Do not create issues in the production project. Use the staging project."
11001100 }
11011101 ]
11021102 }'
from line 1105
11051105 ```bash CLI
11061106 # Allow the tool to run
11071107 ant beta:sessions:events send \
1108 --session-id "$SESSION_ID" \
1109 --event "{type: user.tool_confirmation, tool_use_id: $AGENT_TOOL_USE_EVENT_ID, result: allow}"
1108 --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \
1109 --event '{type: user.tool_confirmation, tool_use_id: sevt_011CZkZbMpR8aS3Wtv5Yq2Ln, result: allow}'
11101110
1111 # Or deny it with an explanation
1111 # Deny another call with an explanation
11121112 ant beta:sessions:events send \
1113 --session-id "$SESSION_ID" \
1114 --event "{type: user.tool_confirmation, tool_use_id: $MCP_TOOL_USE_EVENT_ID, result: deny,
1115 deny_message: Don't create issues in the production project. Use the staging project.}"
1113 --session-id sesn_011CZkZAtmR3yMPDzynEDxu7 \
1114 --event '{type: user.tool_confirmation, tool_use_id: sevt_011CZkZcNqT9bT4Xuw6Zr3Mo, result: deny, deny_message: "Do not create issues in the production project. Use the staging project."}'
11161115 ```
11171116
11181117 ```python Python
11191118 # Allow the tool to run
11201119 client.beta.sessions.events.send(
1121 session.id,
1120 "sesn_011CZkZAtmR3yMPDzynEDxu7",
11221121 events=[
11231122 {
11241123 "type": "user.tool_confirmation",
1125 "tool_use_id": agent_tool_use_event.id,
1124 "tool_use_id": "sevt_011CZkZbMpR8aS3Wtv5Yq2Ln",
11261125 "result": "allow",
11271126 },
11281127 ],
11291128 )
11301129
1131 # Or deny it with an explanation
1130 # Deny another call with an explanation
11321131 client.beta.sessions.events.send(
1133 session.id,
1132 "sesn_011CZkZAtmR3yMPDzynEDxu7",
11341133 events=[
11351134 {
11361135 "type": "user.tool_confirmation",
1137 "tool_use_id": mcp_tool_use_event.id,
1136 "tool_use_id": "sevt_011CZkZcNqT9bT4Xuw6Zr3Mo",
11381137 "result": "deny",
1139 "deny_message": "Don't create issues in the production project. Use the staging project.",
1138 "deny_message": "Do not create issues in the production project. Use the staging project.",
11401139 },
11411140 ],
11421141 )
from line 1143
11441143
11451144 ```typescript TypeScript
11461145 // Allow the tool to run
1147 await client.beta.sessions.events.send(session.id, {
1146 await client.beta.sessions.events.send("sesn_011CZkZAtmR3yMPDzynEDxu7", {
11481147 events: [
11491148 {
11501149 type: "user.tool_confirmation",
1151 tool_use_id: agent_tool_use_event.id,
1150 tool_use_id: "sevt_011CZkZbMpR8aS3Wtv5Yq2Ln",
11521151 result: "allow"
11531152 }
11541153 ]
11551154 });
11561155
1157 // Or deny it with an explanation
1158 await client.beta.sessions.events.send(session.id, {
1156 // Deny another call with an explanation
1157 await client.beta.sessions.events.send("sesn_011CZkZAtmR3yMPDzynEDxu7", {
11591158 events: [
11601159 {
11611160 type: "user.tool_confirmation",
1162 tool_use_id: mcp_tool_use_event.id,
1161 tool_use_id: "sevt_011CZkZcNqT9bT4Xuw6Zr3Mo",
11631162 result: "deny",
1164 deny_message: "Don't create issues in the production project. Use the staging project."
1163 deny_message: "Do not create issues in the production project. Use the staging project."
11651164 }
11661165 ]
11671166 });
from line 1167
11681167 ```
11691168
11701169 ```csharp C#
1170 using Anthropic.Models.Beta.Sessions.Events;
1171
11711172 // Allow the tool to run
1172 await client.Beta.Sessions.Events.Send(session.ID, new()
1173 await client.Beta.Sessions.Events.Send("sesn_011CZkZAtmR3yMPDzynEDxu7", new()
11731174 {
11741175 Events =
11751176 [
11761177 new BetaManagedAgentsUserToolConfirmationEventParams
11771178 {
1178 ToolUseID = agentToolUseEvent.ID,
1179 ToolUseID = "sevt_011CZkZbMpR8aS3Wtv5Yq2Ln",
11791180 Result = "allow",
11801181 },
11811182 ],
11821183 });
11831184
1184 // Or deny it with an explanation
1185 await client.Beta.Sessions.Events.Send(session.ID, new()
1185 // Deny another call with an explanation
1186 await client.Beta.Sessions.Events.Send("sesn_011CZkZAtmR3yMPDzynEDxu7", new()
11861187 {
11871188 Events =
11881189 [
11891190 new BetaManagedAgentsUserToolConfirmationEventParams
11901191 {
1191 ToolUseID = mcpToolUseEvent.ID,
1192 ToolUseID = "sevt_011CZkZcNqT9bT4Xuw6Zr3Mo",
11921193 Result = "deny",
1193 DenyMessage = "Don't create issues in the production project. Use the staging project.",
1194 DenyMessage = "Do not create issues in the production project. Use the staging project.",
11941195 },
11951196 ],
11961197 });
from line 1199
11981199
11991200 ```go Go
12001201 // Allow the tool to run
1201 _, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
1202 _, err := client.Beta.Sessions.Events.Send(ctx, "sesn_011CZkZAtmR3yMPDzynEDxu7", anthropic.BetaSessionEventSendParams{
12021203 Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
12031204 OfUserToolConfirmation: &anthropic.BetaManagedAgentsUserToolConfirmationEventParams{
1204 ToolUseID: agentToolUseEvent.ID,
1205 ToolUseID: "sevt_011CZkZbMpR8aS3Wtv5Yq2Ln",
12051206 Result: anthropic.BetaManagedAgentsUserToolConfirmationEventParamsResultAllow,
12061207 },
12071208 }},
from line 1211
12101211 panic(err)
12111212 }
12121213
1213 // Or deny it with an explanation
1214 _, err = client.Beta.Sessions.Events.Send(ctx, session.ID, anthropic.BetaSessionEventSendParams{
1214 // Deny another call with an explanation
1215 _, err = client.Beta.Sessions.Events.Send(ctx, "sesn_011CZkZAtmR3yMPDzynEDxu7", anthropic.BetaSessionEventSendParams{
12151216 Events: []anthropic.BetaManagedAgentsEventParamsUnion{{
12161217 OfUserToolConfirmation: &anthropic.BetaManagedAgentsUserToolConfirmationEventParams{
1217 ToolUseID: mcpToolUseEvent.ID,
1218 ToolUseID: "sevt_011CZkZcNqT9bT4Xuw6Zr3Mo",
12181219 Result: anthropic.BetaManagedAgentsUserToolConfirmationEventParamsResultDeny,
1219 DenyMessage: anthropic.String("Don't create issues in the production project. Use the staging project."),
1220 DenyMessage: anthropic.String("Do not create issues in the production project. Use the staging project."),
12201221 },
12211222 }},
12221223 })
from line 1227
12261227 ```
12271228
12281229 ```java Java
1230 import com.anthropic.models.beta.sessions.events.BetaManagedAgentsUserToolConfirmationEventParams;
1231 import com.anthropic.models.beta.sessions.events.EventSendParams;
1232
12291233 // Allow the tool to run
12301234 client.beta().sessions().events().send(
1231 session.id(),
1235 "sesn_011CZkZAtmR3yMPDzynEDxu7",
12321236 EventSendParams.builder()
12331237 .addEvent(
12341238 BetaManagedAgentsUserToolConfirmationEventParams.builder()
1235 .toolUseId(agentToolUseEvent.id())
1239 .toolUseId("sevt_011CZkZbMpR8aS3Wtv5Yq2Ln")
12361240 .result(BetaManagedAgentsUserToolConfirmationEventParams.Result.ALLOW)
12371241 .build()
12381242 )
from line 1243
12391243 .build()
12401244 );
12411245
1242 // Or deny it with an explanation
1246 // Deny another call with an explanation
12431247 client.beta().sessions().events().send(
1244 session.id(),
1248 "sesn_011CZkZAtmR3yMPDzynEDxu7",
12451249 EventSendParams.builder()
12461250 .addEvent(
12471251 BetaManagedAgentsUserToolConfirmationEventParams.builder()
1248 .toolUseId(mcpToolUseEvent.id())
1252 .toolUseId("sevt_011CZkZcNqT9bT4Xuw6Zr3Mo")
12491253 .result(BetaManagedAgentsUserToolConfirmationEventParams.Result.DENY)
1250 .denyMessage("Don't create issues in the production project. Use the staging project.")
1254 .denyMessage("Do not create issues in the production project. Use the staging project.")
12511255 .build()
12521256 )
12531257 .build()
from line 1263
12591263
12601264 // Allow the tool to run
12611265 $client->beta->sessions->events->send(
1262 $session->id,
1266 'sesn_011CZkZAtmR3yMPDzynEDxu7',
12631267 events: [
12641268 ManagedAgentsUserToolConfirmationEventParams::with(
1265 toolUseID: $agentToolUseEvent->id,
1269 toolUseID: 'sevt_011CZkZbMpR8aS3Wtv5Yq2Ln',
12661270 result: 'allow',
12671271 ),
12681272 ],
12691273 );
12701274
1271 // Or deny it with an explanation
1275 // Deny another call with an explanation
12721276 $client->beta->sessions->events->send(
1273 $session->id,
1277 'sesn_011CZkZAtmR3yMPDzynEDxu7',
12741278 events: [
12751279 ManagedAgentsUserToolConfirmationEventParams::with(
1276 toolUseID: $mcpToolUseEvent->id,
1280 toolUseID: 'sevt_011CZkZcNqT9bT4Xuw6Zr3Mo',
12771281 result: 'deny',
1278 denyMessage: "Don't create issues in the production project. Use the staging project.",
1282 denyMessage: 'Do not create issues in the production project. Use the staging project.',
12791283 ),
12801284 ],
12811285 );
from line 1288
12841288 ```ruby Ruby
12851289 # Allow the tool to run
12861290 client.beta.sessions.events.send_(
1287 session.id,
1291 "sesn_011CZkZAtmR3yMPDzynEDxu7",
12881292 events: [
12891293 {
12901294 type: "user.tool_confirmation",
1291 tool_use_id: agent_tool_use_event.id,
1295 tool_use_id: "sevt_011CZkZbMpR8aS3Wtv5Yq2Ln",
12921296 result: "allow"
12931297 }
12941298 ]
12951299 )
12961300
1297 # Or deny it with an explanation
1301 # Deny another call with an explanation
12981302 client.beta.sessions.events.send_(
1299 session.id,
1303 "sesn_011CZkZAtmR3yMPDzynEDxu7",
13001304 events: [
13011305 {
13021306 type: "user.tool_confirmation",
1303 tool_use_id: mcp_tool_use_event.id,
1307 tool_use_id: "sevt_011CZkZcNqT9bT4Xuw6Zr3Mo",
13041308 result: "deny",
1305 deny_message: "Don't create issues in the production project. Use the staging project."
1309 deny_message: "Do not create issues in the production project. Use the staging project."
13061310 }
13071311 ]
13081312 )
managed-agents/skills Changed · +7 / -5 lines
from line 50
5050
5151A custom skill is a directory containing a `SKILL.md` file plus any supporting files, uploaded to your workspace as a zip archive or as individual files. Creating the skill returns the `skill_*` ID you reference when attaching it to an agent. Anthropic pre-built skills are already available in every workspace and don’t require this step. To use only pre-built skills, skip to [Attach skills to an agent](https://platform.claude.com/docs/en/managed-agents/skills#attach-skills-to-an-agent).
5252
53These examples omit the optional `display_name` (java, php: `displayName`; csharp, go: `DisplayName`) field, so the skill’s display name is derived from the `name` field in `SKILL.md`. An explicit `display_name` (java, php: `displayName`; csharp, go: `DisplayName`) can be up to 255 characters and doesn’t need to be unique within your workspace.
53These examples omit the optional `display_name` (java, php: `displayName`; csharp, go: `DisplayName`) field, so the skill’s display name comes from the `name` field in `SKILL.md`. An explicit `display_name` (java, php: `displayName`; csharp, go: `DisplayName`) can be up to 255 characters and doesn’t need to be unique within your workspace.
5454
5555<CodeGroup defaultLanguage="CLI">
5656 ```bash cURL
from line 383
383383 ```
384384
385385 ```php PHP
386 use Anthropic\Beta\Agents\BetaManagedAgentsModel;
387
386388 $agent = $client->beta->agents->create(
387389 name: 'Financial Analyst',
388 model: 'claude-opus-5-5',
390 model: BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
389391 system: 'You are a financial analysis agent.',
390392 skills: [
391393 ['type' => 'anthropic', 'skillID' => 'xlsx'],
from line 399
397399 ```ruby Ruby
398400 agent = client.beta.agents.create(
399401 name: "Financial Analyst",
400 model: "claude-opus-5-5",
402 model: Anthropic::Beta::BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
401403 system_: "You are a financial analysis agent.",
402404 skills: [
403405 {type: "anthropic", skill_id: "xlsx"},
from line 411
409411
410412## Load skills from a GitHub repository
411413
412Skills can also live in your code base. When a session mounts a repository through the [`github_repository` resource](https://platform.claude.com/docs/en/managed-agents/github), the repository’s root `.claude/skills` directory is scanned at session start, and each skill found there becomes available to the agent. No upload and no entry in the agent’s `skills` (csharp, go: `Skills`) array are required. The agent receives each discovered skill’s name, description, and path in the sandbox, and reads the skill’s `SKILL.md` when a task matches, including any scripts and resources the skill ships. Discovery relies on the agent’s `read` tool from the [agent toolset](https://platform.claude.com/docs/en/managed-agents/tools), which is enabled by default; an agent with `read` disabled doesn’t load repository skills.
414Skills can also live in your code base. When a session mounts a repository through the [`github_repository` resource](https://platform.claude.com/docs/en/managed-agents/github), a scan of the repository’s root `.claude/skills` directory runs at session start. Each skill found there becomes available to the agent. You don’t need to upload these skills or add them to the agent’s `skills` (csharp, go: `Skills`) array. The agent receives each discovered skill’s name, description, and path in the sandbox. When a task matches, the agent reads the skill’s `SKILL.md`, including any scripts and resources the skill ships. Discovery relies on the agent’s `read` tool from the [agent toolset](https://platform.claude.com/docs/en/managed-agents/tools), which is enabled by default; an agent with `read` disabled doesn’t load repository skills.
413415
414416<Warning>
415417 Repository skills are agent instructions, so a mounted repository is part of your agent’s trust boundary. Anyone who can commit to the repository (a merged external pull request, a compromised dependency, a contributor) can add or change a skill. The platform loads that skill at session start without a review step, and session tools such as `bash` and `web_fetch` give its instructions real reach. Mount only repositories you trust, and review `.claude/skills` before mounting a repository that accepts outside contributions.
from line 600
598600
599601Discovered skills follow the checked-out state of the repository: the `checkout` (csharp, go: `Checkout`) branch or commit when the resource sets one, otherwise the repository’s default branch. The scan runs once, when the session starts. Commits pushed mid-session are not picked up; to load updated skills, start a new session.
600602
601Repository skills work alongside skills attached through the agent’s `skills` (csharp, go: `Skills`) array. If a repository skill shares a name with an attached skill, or with a skill from another mounted repository, both are available; each is announced with its own path.
603Repository skills work alongside skills attached through the agent’s `skills` (csharp, go: `Skills`) array. If a repository skill shares a name with an attached skill, or with a skill from another mounted repository, both are available. The agent receives each one with its own path.
602604
603605## Next steps
604606
managed-agents/tools Changed · +3 / -2 lines
from line 61
6161
6262Enable the full toolset with `agent_toolset_20260401` when creating an agent. Use the `configs` (csharp, go: `Configs`) array to disable specific tools or override their settings. Each entry is identified by its `name` (csharp, go: `Name`), which takes a value from the Name column in [Available tools](https://platform.claude.com/docs/en/managed-agents/tools#available-tools). An entry also accepts an optional `type` (csharp, go: `Type`) field with the same value.
6363
64Each config entry can also set a `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). The policy controls whether the tool’s calls run without confirmation, require confirmation, or are evaluated individually by the server. See [Permission policies](https://platform.claude.com/docs/en/managed-agents/permission-policies) for the available policy types.
64Each config entry can also set a `permission_policy` (java, php: `permissionPolicy`; csharp, go: `PermissionPolicy`). The policy controls whether the tool’s calls run without confirmation, require confirmation, or go to the server, which evaluates each call. See [Permission policies](https://platform.claude.com/docs/en/managed-agents/permission-policies) for the available policy types.
6565
6666The following example enables the toolset and disables `web_fetch`:
6767
from line 424
424424 ```
425425
426426 ```java Java
427 import com.anthropic.core.JsonValue;
427428 import com.anthropic.models.beta.agents.*;
428429 import java.util.Map;
429430
from line 487
486487 ```
487488</CodeGroup>
488489
489A custom tool’s name can’t start with `mcp__` or `ant__`, or match the name of a built-in agent tool. A request that breaks this rule returns a 400 error. An agent that already has a custom tool whose name starts with `ant__` accepts an update only if the update sends `tools` (csharp, go: `Tools`) without that name, so rename or remove the tool in your next update. A new session is refused with a 400 error if such a tool is on its agent (after any [overrides](https://platform.claude.com/docs/en/managed-agents/sessions#override-agent-configuration-for-a-session)), on an agent in the `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `subagents` (csharp, go: `Subagents`), or on an agent in the `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `workflows` (csharp, go: `Workflows`). Sessions that already exist aren’t affected.
490New custom tool names can’t start with `mcp__` or `ant__`, or match the name of a built-in agent tool. A request that breaks this rule returns a 400 error. However, an existing custom tool might start with `ant__`. An agent with such a tool accepts an update only if the update sends `tools` (csharp, go: `Tools`) without that name, so rename or remove the tool in your next update. A new session is refused with a 400 error if such a tool is on its agent (after any [overrides](https://platform.claude.com/docs/en/managed-agents/sessions#override-agent-configuration-for-a-session)), on an agent in the `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `subagents` (csharp, go: `Subagents`), or on an agent in the `predefined_agents` (java, php: `predefinedAgents`; csharp, go: `PredefinedAgents`) list of `workflows` (csharp, go: `Workflows`). Sessions that already exist aren’t affected.
490491
491492The agent calls its custom tools during a session. To receive the calls and return results, see [Answer tool calls that pause the session](https://platform.claude.com/docs/en/managed-agents/events-and-streaming#handling-custom-tool-calls).
492493
managed-agents/tools-web-restrictions Changed · +20 / -18 lines
from line 55
5555
5656## Set domain lists on an agent
5757
58The following example creates an agent that limits `web_search` to two sites and blocks one host for `web_fetch`. It also sets `user_location` (java, php: `userLocation`; csharp, go: `UserLocation`) and `max_content_tokens` (java, php: `maxContentTokens`; csharp, go: `MaxContentTokens`), which [Settings](https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions#settings) describes. The response echoes the `configs` (csharp, go: `Configs`) array.
58The following example creates an agent that limits `web_search` to two sites and blocks one host for `web_fetch`. It also sets `user_location` (java, php: `userLocation`; csharp, go: `UserLocation`) and `max_content_tokens` (java, php: `maxContentTokens`; csharp, go: `MaxContentTokens`). [Settings](https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions#settings) describes both.
5959
6060<CodeGroup defaultLanguage="CLI">
6161 ```bash cURL
from line 121
121121 ```
122122 </File>
123123
124 [`ant apply`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply) creates the agent and prints its ID, not the `configs` array.
124 [`ant apply`](https://platform.claude.com/docs/en/cli-sdks-libraries/cli/apply) creates the agent and prints its ID.
125125 </CodeGroupItem>
126126
127127 ```python Python
from line 326
326326 ```php PHP
327327 use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401;
328328 use Anthropic\Beta\Agents\BetaManagedAgentsAgentToolset20260401Params;
329 use Anthropic\Beta\Agents\BetaManagedAgentsModel;
329330 use Anthropic\Beta\Agents\BetaManagedAgentsUserLocation;
330331 use Anthropic\Beta\Agents\BetaManagedAgentsWebFetchToolConfigParams;
331332 use Anthropic\Beta\Agents\BetaManagedAgentsWebSearchToolConfigParams;
from line 336
335336
336337 $agent = $client->beta->agents->create(
337338 name: 'Research Agent',
338 model: 'claude-opus-5-5',
339 model: BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
339340 tools: [
340341 BetaManagedAgentsAgentToolset20260401Params::with(
341342 configs: [
from line 368
367368
368369 agent = client.beta.agents.create(
369370 name: "Research Agent",
370 model: "claude-opus-5-5",
371 model: Anthropic::Beta::BetaManagedAgentsModel::CLAUDE_OPUS_5_5,
371372 tools: [
372373 {
373374 type: :agent_toolset_20260401,
from line 388
387388 ]
388389 )
389390
390 case agent.tools.first
391 in Anthropic::Models::Beta::BetaManagedAgentsAgentToolset20260401 => toolset
392 puts JSON.pretty_generate(toolset.configs.map(&:to_h))
391 agent.tools.each do |tool|
392 if tool.is_a?(Anthropic::Beta::BetaManagedAgentsAgentToolset20260401)
393 puts JSON.pretty_generate(tool.configs.map(&:to_h))
394 end
393395 end
394396 ```
395397</CodeGroup>
from line 419
417419
418420## Domain list rules
419421
420These rules apply to `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) and `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) alike. A request that breaks one is rejected, as [Validation errors](https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions#validation-errors) describes.
422These rules apply to `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) and `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) alike. The API rejects a request that breaks any of these rules, as [Validation errors](https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions#validation-errors) describes.
421423
422424* **At most one list on an entry:** Set either `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) or `blocked_domains` (java, php: `blockedDomains`; csharp, go: `BlockedDomains`) on an entry, not both.
423425* **List size:** Each list holds 1 to 64 domains, each 1 to 255 characters.
from line 449
447449| A single-label name | `intranet` | A full domain such as `example.co.uk` |
448450| Non-ASCII characters, as in an internationalized domain name | | The `xn--` (Punycode) form |
449451
450A domain is also rejected if it contains credentials or whitespace, or if one of its labels starts or ends with a hyphen. `localhost` and hosts ending in `.localhost`, `.local`, `.internal`, `.localdomain`, or `.invalid` are rejected too.
452The API also rejects a domain that contains credentials or whitespace, or that has a label starting or ending with a hyphen. It rejects `localhost` and hosts ending in `.localhost`, `.local`, `.internal`, `.localdomain`, or `.invalid` too.
451453
452454### Path suffixes on web search domains
453455
from line 461
459461
460462The API validates these settings when you [create an agent](https://platform.claude.com/docs/en/managed-agents/agent-setup#create-an-agent) or [update an agent](https://platform.claude.com/docs/en/managed-agents/agent-setup#update-an-agent). It also validates them when you create or update a session that supplies `tools` (csharp, go: `Tools`).
461463
462Format and limit violations are rejected with a 400 `invalid_request_error`:
464The API rejects format and limit violations with a 400 `invalid_request_error`:
463465
464| Violation | Error message |
465| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
466| An entry sets both lists. | Includes `Only one of allowed_domains or blocked_domains may be set.` |
467| A list is empty. | Includes `allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null.` |
468| A domain breaks a format rule. | Names the domain’s list and zero-based position. For example, `allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com"` |
466| Violation | Error message |
467| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
468| An entry sets both lists. | Includes `Only one of allowed_domains or blocked_domains may be set.` |
469| A list is empty. | Includes `allowed_domains: Empty list of domains is ambiguous. Provide at least one domain or null.` |
470| A domain breaks a format rule. | Names the domain’s list and zero-based position, as in `allowed_domains.0: IP addresses are not supported; provide a plain hostname like "example.com"` |
469471
470472On the same requests, the API also rejects three settings that depend on the search and fetch providers:
471473
472474* A domain in `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) that Anthropic’s crawler is not allowed to access.
473* A `user_location.country` that the search provider does not support. The message ends in `user_location.country: not a country the search provider supports`.
474* A `user_location.timezone` that is not a valid IANA name.
475* A `user_location.country` (java, php: `userLocation.country`; csharp, go: `UserLocation.Country`) that the search provider does not support. The message ends in `user_location.country: not a country the search provider supports`.
476* A `user_location.timezone` (java, php: `userLocation.timezone`; csharp, go: `UserLocation.Timezone`) that is not a valid IANA time zone name.
475477
476478In a cloud environment with `limited` [networking](https://platform.claude.com/docs/en/managed-agents/environments#networking), session create and update also check `allowed_domains` (java, php: `allowedDomains`; csharp, go: `AllowedDomains`) against the environment’s `allowed_hosts` (java, php: `allowedHosts`; csharp, go: `AllowedHosts`). See the rule in [Set domain lists on an agent](https://platform.claude.com/docs/en/managed-agents/tools-web-restrictions#set-domain-lists-on-an-agent).
477479
models/fable-5-2/migration-guide Changed · +73 / -53 lines
from line 28
2828* **Sampling parameters:** Omit `temperature`, `top_p`, and `top_k`, as on Claude Fable 5.1. See [Sampling parameters](https://platform.claude.com/docs/en/build-with-claude/thinking#sampling-parameters) for the values that return a 400 error.
2929* **Tool choice:** `{type: "auto"}` (the default) and `{type: "none"}` are supported. Forcing a tool call with `{type: "any"}` or `{type: "tool", name: "..."}` returns a 400 error, unchanged from Claude Fable 5.1.
3030* **Structured outputs:** In an organization with [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek) (CMEK), [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) aren’t available for either model, as for Claude Fable 5.1. That covers both strict tool use and JSON outputs. If your requests set `strict: true` or `output_config.format` there, remove them and validate the output in your code.
31* **Preserved thinking across models:** On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 read each other’s thinking blocks and those from other models, including Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5. No other model reads their blocks. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models) for the list.
32* **Account-bound thinking:** Thinking blocks from Claude Fable 5.2 and Claude Mythos 5.2 work only in the account that produced them, or in an account linked to it. When another account sends one of these blocks, the API drops the block before the model receives it, and the request succeeds. On the Claude API and Claude Models on Google Cloud (Google managed), with the `thinking-binding-controls-2026-08-01` beta header, the response lists each dropped block in `input_transformations` with `reason: "organization_binding_mismatch"`. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
31* **Preserved thinking across models:** On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 read each other’s thinking blocks and those from other models, including Claude Opus 5.5, Claude Sonnet 5.5, and Claude Haiku 5.5. No other model reads their blocks. See [Which model switches keep the reasoning on the Claude API](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#which-model-switches-keep-reasoning) for the list.
32* **Account-bound thinking:** Thinking blocks from Claude Fable 5.2 and Claude Mythos 5.2 work only in the account that produced them, or in an account linked to it. When another account sends one of these blocks, the API drops the block before the model receives it, and the request succeeds. On the Claude API and Claude Models on Google Cloud (Google managed), with the `thinking-binding-controls-2026-08-01` beta header, the response lists each dropped block in `input_transformations` with `reason: "organization_binding_mismatch"`. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
3333* **Context window and output:** A [1M token context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) by default, and up to 128k output tokens for each request.
3434* **Pricing:** $8 USD per million input tokens and $40 USD per million output tokens, compared with $10 USD and $50 USD on Claude Fable 5.1 and Claude Mythos 5.1. Prompt cache reads are $0.20 USD per million tokens, compared with $0.25 USD on those models. See [Pricing](https://platform.claude.com/docs/en/about-claude/pricing).
3535* **Data retention:** Both models require 30-day data retention, aren’t available under zero data retention (ZDR) arrangements unless expressly authorized by Anthropic, and are designated Covered Models, the same as Claude Fable 5.1 and Claude Mythos 5.1. On the Claude API, a request from an organization or workspace without 30-day retention returns a 400 `invalid_request_error`. Organizations with a ZDR arrangement should contact their Anthropic account team, or configure retention for individual workspaces. See [Model-specific data retention requirements](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements) for per-platform details.
3636* **Priority Tier:** Neither model is supported on [Priority Tier](https://platform.claude.com/docs/en/api/service-tiers#supported-models).
37* **Fast mode:** Both models support [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) in Messages API requests. [Availability of fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode#feature-availability) lists each model’s platforms.
37* **Fast mode:** Both models support [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) in Messages API requests. For each model’s platforms, see [Availability of fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode#feature-availability).
3838
3939Where the two models diverge:
4040
from line 43
4343
4444## Migrating to Claude Fable 5.2 from Claude Fable 5.1
4545
46Migration is mostly drop-in. The API surface, always-on adaptive thinking, the forced tool choice restriction, refusal handling, `stop_details` categories, and the data retention requirement all match Claude Fable 5.1. Claude Fable 5.2 costs less: $8 USD per million input tokens and $40 USD per million output tokens, compared with $10 USD and $50 USD on Claude Fable 5.1. Four changes can break your code. The [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check), which catches edits to earlier turns, applies to every account. Claude Fable 5.1 can’t read Claude Fable 5.2’s thinking blocks. The earlier computer use tool, `computer_20251124`, returns a 400 error on every platform except Amazon Bedrock. With the advisor tool, a Claude Fable 5.2 executor accepts only Claude Fable 5.2 or Claude Mythos 5.2 as its advisor.
46Migration is mostly drop-in. The API surface, always-on adaptive thinking, the forced tool choice restriction, refusal handling, `stop_details` categories, and the data retention requirement all match Claude Fable 5.1. Claude Fable 5.2 costs less: $8 USD per million input tokens and $40 USD per million output tokens, compared with $10 USD and $50 USD on Claude Fable 5.1. Four changes can break your code. Failing the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check), which catches edits to earlier turns, returns a 400 error (see [Thinking block bound to a different conversation](https://platform.claude.com/docs/en/api/errors#thinking-block-conversation-mismatch)). Claude Fable 5.1 can’t read Claude Fable 5.2’s thinking blocks. The earlier computer use tool, `computer_20251124`, returns a 400 error on every platform except Amazon Bedrock. With the advisor tool, a Claude Fable 5.2 executor accepts only Claude Fable 5.2 or Claude Mythos 5.2 as its advisor.
4747
4848### Update your model name
4949
from line 56
5656
5757### Breaking changes
5858
591. **The prefix check applies to every account:** Each `thinking` block from Claude Fable 5.2 is valid only against the `system` prompt, `tools`, and conversation history that preceded it, as on Claude Fable 5.1. Claude Fable 5.2 enforces this [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check) for every account, whatever its age. Claude Fable 5.1 enforces it by default for accounts created on or after August 31, 2026. So on an older account, requests that pass on Claude Fable 5.1 can fail on Claude Fable 5.2.
591. **Failed prefix checks return a 400 error:** On Claude Fable 5.2, each request gets a [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check). A prefix check fails if you change `system`, `tools`, or earlier messages mid-conversation and then send thinking blocks back. If a prefix check fails, the request receives a 400 error.
6060
61 Nothing changes for you if Claude Code, claude.ai, [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), or the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) manages your conversation history. If your code builds the `messages` array itself, compare what it does between requests with the list in [Who the prefix check affects](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#who-is-affected). A request that sends a thinking block back after one of those edits returns a 400 error:
61 Nothing changes for you if Claude Code, claude.ai, [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), or the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) manages your conversation history. If your code builds the `messages` array itself, compare what it does between requests with [If your code changes the system prompt, tools, or history](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#what-to-check). If your code makes one of those changes between requests, the thinking that already follows the change is invalid. A later request that sends it back returns a 400 error:
6262
6363 ```text wrap
6464 messages.5.content.0: Invalid `signature` in `thinking` block. The block is bound to a different conversation. Remove the block, or set `thinking.block_binding.prefix_mismatch_behavior` to "drop_block". That setting requires the `thinking-binding-controls-2026-08-01` value in the `anthropic-beta` header.
6565 ```
6666
67 Retrying the same request body doesn’t clear the error. To find these edits before you switch production traffic, run the check in [Check whether your code edits the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted) against the model you use now, Claude Fable 5.1 or Claude Opus 5.5. If you use the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) without [pinning a server’s tool list](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#pin-mcp-tool-list), also run the check against `claude-fable-5-2`: a tool list that changes between requests is an edit for Claude Fable 5.2 thinking blocks, but not for Claude Fable 5.1 or Claude Opus 5.5 blocks. You can run this check from any account. [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) gives the fix for each pattern.
67 Retrying the same request body doesn’t clear the error. To find these edits before you switch production traffic, run the test in [Test your code for prefix check failures](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/fix-bound-to-a-different-conversation#how-to-tell-whether-your-integration-is-impacted) against the model you use now, Claude Fable 5.1 or Claude Opus 5.5. If you use the [MCP connector](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector) without [pinning a server’s tool list](https://platform.claude.com/docs/en/agents-and-tools/mcp-connector#pin-mcp-tool-list), also run the test against `claude-fable-5-2`. For Claude Fable 5.2 thinking blocks, a tool list that changes between requests is an edit. For Claude Fable 5.1 or Claude Opus 5.5 blocks, it isn’t. For the fix for each pattern, see [Change tools or instructions without failing the prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/change-tools-or-instructions).
6868
69 In production, leave `prefix_mismatch_behavior` at its default, `"error"`, if a mismatch can only mean a bug in your code. To drop the affected blocks and continue without that reasoning while you fix the edit, set it to `"drop_block"`. Treat that as a stopgap, not a long-term setting: [dropping blocks can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost).
69 In production, leave `prefix_mismatch_behavior` at its default, `"error"`, if a mismatch can only mean a bug in your code. To drop the affected blocks and continue without that reasoning while you fix the edit, set it to `"drop_block"`. Treat that as a stopgap, not a long-term setting: [dropping blocks can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/fix-bound-to-a-different-conversation#drop-block-cost).
7070
712. **Claude Fable 5.1 can’t read Claude Fable 5.2’s thinking blocks:** On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 reads Claude Fable 5.1’s blocks, so a conversation that moves from `claude-fable-5-1` onto `claude-fable-5-2` keeps its earlier reasoning. In the other direction, Claude Fable 5.1 can’t read Claude Fable 5.2’s blocks. If a router switch, a client-side retry, or a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) moves a conversation from Claude Fable 5.2 to another model, Claude Fable 5.1 included, the API drops the blocks that model can’t read. The request succeeds, and you aren’t billed for the dropped input tokens. The model then works without that reasoning, which can raise cost and latency on the first turn after the switch. With the `thinking-binding-controls-2026-08-01` beta header, `input_transformations` lists each dropped block with `reason: "model_binding_mismatch"`. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
71 You can continue a Claude Fable 5.1 or Claude Opus 5.5 conversation on Claude Fable 5.2. If you changed `system`, `tools`, or earlier messages in it, it can get the 400 error: see [Thinking block bound to a different conversation](https://platform.claude.com/docs/en/api/errors#thinking-block-conversation-mismatch).
7272
733. **Use the computer use toolset instead of `computer_20251124`:** A `tools` entry of type `computer_20251124` returns a 400 error on every platform except Amazon Bedrock. Declare the `computer_toolset_20260801` toolset instead: drop the beta header and send the entry with no `name` or display dimensions. Then update your agent loop for the toolset, as [Migrate from `computer_20251124`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124) describes. On Amazon Bedrock, Claude Fable 5.2 and Claude Mythos 5.2 accept the earlier tool: with the InvokeModel API, send `computer-use-2025-11-24` in the `anthropic_beta` array of the request body.
732. **Claude Fable 5.1 can’t read Claude Fable 5.2’s thinking blocks:** On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 reads Claude Fable 5.1’s blocks, so a conversation that moves from `claude-fable-5-1` onto `claude-fable-5-2` keeps its earlier reasoning. In the other direction, Claude Fable 5.1 can’t read Claude Fable 5.2’s blocks.
7474
754. **A Claude Fable 5.2 executor needs a Claude Fable 5.2 or Claude Mythos 5.2 advisor:** With the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool), which is in beta, the advisor must be at least as capable as the executor. A Claude Fable 5.2 or Claude Mythos 5.2 executor accepts only Claude Fable 5.2 or Claude Mythos 5.2 as its advisor, and any other advisor, including Claude Fable 5.1 and Claude Mythos 5.1, returns a 400 `invalid_request_error`. When you change the executor’s model ID, set the `model` in the advisor tool definition to `claude-fable-5-2` or `claude-mythos-5-2`. Changing the advisor’s `model` is an edit to `tools`, so make the change in new conversations. A request that sends earlier thinking blocks back after the change fails the prefix check (see [The prefix check applies to every account](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-preserved-thinking)) and returns a 400 error, unless you set `prefix_mismatch_behavior` to `"drop_block"`. To keep your current executor and change only the advisor, set the advisor’s `model` to `claude-fable-5-2`: every executor model accepts it. A Claude Fable 5.2 advisor returns its advice encrypted, so if your code reads the advice text, see [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants). The same pairs apply to the advisor of a [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) agent, so set that advisor’s `model` to one of these two models when you change the agent’s. See [Model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility) and [Give the session an advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
75 If a router switch, a client-side retry, or a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) moves a conversation from Claude Fable 5.2 to another model, Claude Fable 5.1 included, the API drops the blocks that model can’t read. The request succeeds, and you aren’t billed for the dropped input tokens. The model then works without that reasoning, which can raise cost and latency on the first turn after the switch.
7676
77 With the `thinking-binding-controls-2026-08-01` beta header, `input_transformations` lists each dropped block with `reason: "model_binding_mismatch"`. See [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
78
793. **Use the computer use toolset instead of `computer_20251124`:** A `tools` entry of type `computer_20251124` returns a 400 error on every platform except Amazon Bedrock. Declare the `computer_toolset_20260801` toolset instead: drop the beta header and send the entry with no `name` or display dimensions. Then update your agent loop for the toolset (see [Migrate from `computer_20251124`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124)). On Amazon Bedrock, Claude Fable 5.2 and Claude Mythos 5.2 accept the earlier tool: with the InvokeModel API, send `computer-use-2025-11-24` in the `anthropic_beta` array of the request body.
80
814. **A Claude Fable 5.2 executor needs a Claude Fable 5.2 or Claude Mythos 5.2 advisor:** With the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool), which is in beta, the advisor must be at least as capable as the executor. A Claude Fable 5.2 or Claude Mythos 5.2 executor accepts only Claude Fable 5.2 or Claude Mythos 5.2 as its advisor. For these executors, any other advisor, including Claude Fable 5.1 and Claude Mythos 5.1, returns a 400 `invalid_request_error`. See [Model compatibility](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#model-compatibility).
82
83 When you change the executor’s model ID, set the `model` in the advisor tool definition to `claude-fable-5-2` or `claude-mythos-5-2`. Changing the advisor’s `model` is an edit to `tools`, so make the change in new conversations. A request that sends earlier thinking blocks back after the change fails the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check). The request returns a 400 error, unless you set `prefix_mismatch_behavior` to `"drop_block"`.
84
85 To keep your current executor and change only the advisor, set the advisor’s `model` to `claude-fable-5-2`: every executor model accepts it.
86
87 A Claude Fable 5.2 advisor returns its advice encrypted. If your code reads the advice text, see [Result variants](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool#result-variants).
88
89 If a [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview) agent has an advisor, the same model requirements apply to that advisor. When you change the agent’s model, set that advisor’s `model` to `claude-fable-5-2` or `claude-mythos-5-2`. See [Give the session an advisor](https://platform.claude.com/docs/en/managed-agents/multiagent-orchestration#give-the-session-an-advisor).
90
7791### Behavior changes
7892
79931. **Prompt lines that ask for less thinking don’t stop the model from thinking at `medium` effort and above:** Claude Fable 5.1 usually follows a line such as “answer directly without deliberating.” In Anthropic’s testing, such a line didn’t stop Claude Fable 5.2 from thinking at `medium` and above. Remove these lines and lower the effort level. See [Calibrate effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#calibrate-effort).
from line 102
88102* Check your [rate limits](https://platform.claude.com/docs/en/api/rate-limits#rate-limits) before you move production traffic. Claude Fable 5.2 has its own rate limit, separate from the one Claude Fable 5.1 and Claude Fable 5 share.
89103* If you use computer use through `computer_20251124` anywhere except Amazon Bedrock, Claude Fable 5.2 returns a 400 error for that tool. Declare `computer_toolset_20260801` instead and update your agent loop for the toolset.
90104* If you use the advisor tool with Claude Fable 5.2 as the executor, set the advisor’s `model` to `claude-fable-5-2` or `claude-mythos-5-2`.
91* If your code builds the `messages` array itself, run a session with the `thinking-binding-controls-2026-08-01` beta header and `prefix_mismatch_behavior: "drop_block"`, log `input_transformations`, and fix every `prefix_binding_mismatch` entry. Do this even if your account never hit the check on Claude Fable 5.1.
92* Pick a production `prefix_mismatch_behavior`: `"error"` (the default), or `"drop_block"` as a stopgap while you fix the edits, because [dropping blocks can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost). Monitor the 400 errors or the `input_transformations` entries.
105* If your code builds the `messages` array itself, run a session with the `thinking-binding-controls-2026-08-01` beta header and `prefix_mismatch_behavior: "drop_block"`, log `input_transformations`, and fix every `prefix_binding_mismatch` entry.
106* Pick a production `prefix_mismatch_behavior`: `"error"` (the default), or `"drop_block"` as a stopgap while you fix the edits, because [dropping blocks can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/fix-bound-to-a-different-conversation#drop-block-cost). Monitor the 400 errors or the `input_transformations` entries.
93107* Keep passing `thinking` blocks back unchanged on every turn, including empty ones. If a router or fallback can move a conversation from Claude Fable 5.2 to Claude Fable 5.1, expect Claude Fable 5.1 to run without Claude Fable 5.2’s blocks.
94* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Fable 5.2 thinking blocks that another account produced. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
108* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Fable 5.2 thinking blocks that another account produced. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
95109* Re-run your [effort sweep](https://platform.claude.com/docs/en/build-with-claude/effort#recommended-effort-levels-for-claude-fable-5-2) on your own evals, and re-baseline cost and latency.
96110* Check the system prompts, skills, and other instructions you carry over against [Review prompts and harnesses designed for earlier models](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#review-instructions-written-for-earlier-models).
97111
from line 113
99113
100114[Claude Mythos 5.2](https://platform.claude.com/docs/en/models/mythos-5-2/overview) is the counterpart to Claude Fable 5.2 for organizations verified through Anthropic’s verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842). Confirm that your organization has access to Claude Mythos 5.2 before you switch model IDs.
101115
102Claude Mythos 5.2 enforces the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check) for every account, as Claude Fable 5.2 does. On the Claude API, Claude Mythos 5.1 already returns the error for every account (see [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement)). On Amazon Bedrock, Claude Mythos 5.2 returns the 400 error for edited earlier turns, where Claude Mythos 5.1 accepts such a request. If your code changes `system`, `tools`, or earlier messages between requests, see [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) for what to change and how to test, and run the test against `claude-mythos-5-2`.
116On Claude Mythos 5.2, a request that fails the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check) gets a 400 error. On Amazon Bedrock, this error is a breaking change from Claude Mythos 5.1. If your code changes `system`, `tools`, or earlier messages between requests, see [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) for what to change and how to test, and run the test against `claude-mythos-5-2`.
103117
104On the Claude API and Claude Models on Google Cloud (Google managed), Claude Mythos 5.2 reads Claude Mythos 5.1’s thinking blocks, so a conversation that moves from `claude-mythos-5-1` onto `claude-mythos-5-2` keeps its earlier reasoning. In the other direction, Claude Mythos 5.1 can’t read Claude Mythos 5.2’s blocks: the API drops them, and the request succeeds. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
118On the Claude API and Claude Models on Google Cloud (Google managed), Claude Mythos 5.2 reads Claude Mythos 5.1’s thinking blocks, so a conversation that moves from `claude-mythos-5-1` onto `claude-mythos-5-2` keeps its earlier reasoning. In the other direction, Claude Mythos 5.1 can’t read Claude Mythos 5.2’s blocks: the API drops them, and the request succeeds. See [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
105119
106120With the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool), which is in beta, a Claude Mythos 5.2 executor accepts only Claude Mythos 5.2 or Claude Fable 5.2 as its advisor. A Claude Mythos 5.1 or Claude Fable 5.1 advisor returns a 400 error. See [A Claude Fable 5.2 executor needs a Claude Fable 5.2 or Claude Mythos 5.2 advisor](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-advisor-pairs).
107121
from line 136
122136* If you use computer use through `computer_20251124` anywhere except Amazon Bedrock, Claude Mythos 5.2 returns a 400 error for that tool. Declare `computer_toolset_20260801` instead and update your agent loop for the toolset.
123137* If you use the advisor tool with Claude Mythos 5.2 as the executor, set the advisor’s `model` to `claude-mythos-5-2` or `claude-fable-5-2`.
124138* Keep passing `thinking` blocks back unchanged on every turn, including empty ones.
125* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Mythos 5.2 thinking blocks that another account produced. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
126* If your code builds the `messages` array itself, run the check in [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) against `claude-mythos-5-2`, fix every `prefix_binding_mismatch` entry, and keep conversation history append-only (see [What counts as an edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#what-counts-as-an-edit)). An append-only history also keeps the prompt cache warm.
139* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Mythos 5.2 thinking blocks that another account produced. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
140* If your code builds the `messages` array itself, run the test in [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) against `claude-mythos-5-2`, fix every `prefix_binding_mismatch` entry, and keep conversation history append-only (see [What counts as a change](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#what-counts-as-an-edit)). An append-only history also keeps the prompt cache warm.
127141* Handle `stop_reason: "refusal"` and read `stop_details.category` before response content. See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback).
128142* Re-run your effort sweep, and re-baseline cost and latency.
129143* Check the system prompts, skills, and other instructions you carry over against [Review prompts and harnesses designed for earlier models](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#review-instructions-written-for-earlier-models).
from line 157
143157
1441581. **Data retention is required:** Claude Fable 5.2 requires 30-day data retention and isn’t available under a zero data retention (ZDR) arrangement unless expressly authorized by Anthropic. If your organization or workspace runs Claude Opus 5.5 under ZDR, enable 30-day retention for a workspace or contact your Anthropic account team before you switch. Otherwise, on the Claude API, every request to Claude Fable 5.2 returns a 400 `invalid_request_error`. See [Model-specific data retention requirements](https://platform.claude.com/docs/en/manage-claude/api-and-data-retention#model-specific-data-retention-requirements).
145159
1462. **The prefix check applies to every account:** Claude Opus 5.5 enforces the prefix check by default for accounts created on or after August 31, 2026. Claude Fable 5.2 enforces it for every account, whatever its age. If your account is older and your code changes `system`, `tools`, or earlier messages between requests, requests that work on Claude Opus 5.5 can fail on Claude Fable 5.2. To test before you switch, see [The prefix check applies to every account](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-preserved-thinking).
1602. **Failed prefix checks return a 400 error:** On Claude Fable 5.2, each request gets a [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check). A prefix check fails if you change `system`, `tools`, or earlier messages mid-conversation and then send thinking blocks back. If a prefix check fails, the request receives a 400 error. To test your code before you switch, see [how to find requests that fail](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-preserved-thinking).
147161
1481623. **Claude Opus 5.5 can’t read Claude Fable 5.2’s thinking blocks:** A conversation that moves from Claude Fable 5.2 to Claude Opus 5.5 keeps its text and tool calls, but the turns after the switch run without Claude Fable 5.2’s reasoning. The API drops those blocks before the model receives them, the request succeeds, and the dropped blocks aren’t billed. Expect higher cost and latency on the first turn after the switch. In the other direction, on the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 reads Claude Opus 5.5’s thinking blocks, so a conversation that moves from `claude-opus-5-5` onto `claude-fable-5-2` keeps its earlier reasoning.
149163
from line 188
174188* If your organization has a ZDR arrangement, enable 30-day retention for the workspace, or confirm eligibility with your Anthropic account team, before anything else.
175189* Update the model ID from `claude-opus-5-5` to `claude-fable-5-2`.
176190* Check your [rate limits](https://platform.claude.com/docs/en/api/rate-limits#rate-limits) before you move production traffic. Claude Fable 5.2’s rate limit is separate from Claude Opus 5.5’s, with lower token limits at each tier.
177* If your code builds the `messages` array itself, run the test in [The prefix check applies to every account](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-preserved-thinking), even if your account never hit the check on Claude Opus 5.5.
191* If your code builds the `messages` array itself, run the test in [Failed prefix checks return a 400 error](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-preserved-thinking).
178192* Handle every `stop_details.category`. If you set an explicit `fallbacks` list, name only Claude Fable 5.2’s permitted targets.
179193* If a router or fallback moves conversations from Claude Fable 5.2 to Claude Opus 5.5, expect the turns after the switch to run without Claude Fable 5.2’s thinking blocks.
180* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Fable 5.2 thinking blocks that another account produced. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
194* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Fable 5.2 thinking blocks that another account produced. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
181195* If you use fast mode in Messages API requests, keep `speed: "fast"` only on a platform or hosting option where [Availability of fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode#feature-availability) lists the model you move to. On those platforms and hosting options, re-baseline cost against the [fast mode prices](https://platform.claude.com/docs/en/about-claude/pricing#fast-mode-pricing). On every other platform or hosting option, and in Claude Managed Agents, remove `speed: "fast"`. You don’t need the `fast-mode-2026-02-01` beta header. On the Claude API, requests that send it keep working. Claude in Microsoft Foundry is the exception: there, remove `speed: "fast"` and send requests to a `claude-fable-5-2-fast` deployment.
182196* If you use the advisor tool with Claude Fable 5.2 as the executor, set the advisor’s `model` to `claude-fable-5-2` or `claude-mythos-5-2`.
183197* In an organization with [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek), remove `strict: true` and `output_config.format`, and validate the output in your code.
from line 200
186200
187201## Migrating to Claude Fable 5.2 from Claude Fable 5
188202
189The API surface, context window and output limits, tokenizer, always-on adaptive thinking, and refusal handling all match Claude Fable 5. Some of the following changes also apply when you move from Claude Mythos 5 to Claude Mythos 5.2. [Migrating to Claude Mythos 5.2 from Claude Mythos 5](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#migrating-from-claude-mythos-5-to-claude-mythos-5-2) says which ones.
203The API surface, context window and output limits, tokenizer, always-on adaptive thinking, and refusal handling all match Claude Fable 5. Some of the following changes also apply when you move from Claude Mythos 5 to Claude Mythos 5.2. For which ones, see [Migrating to Claude Mythos 5.2 from Claude Mythos 5](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#migrating-from-claude-mythos-5-to-claude-mythos-5-2).
190204
191205### Update your model name
192206
from line 215
201215
202216 To get the tool call without forcing it, leave `tool_choice` at `auto` and name the tool in your instruction. Set `strict: true` on the tool so the call matches your schema. See [Strict tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/strict-tool-use). If you forced a tool only to get schema-valid JSON, use [JSON outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs#usage) instead. In an organization with [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek), [structured outputs](https://platform.claude.com/docs/en/build-with-claude/structured-outputs) aren’t available for Claude Fable 5.2 or Claude Mythos 5.2. That covers both strict tool use and JSON outputs. There, keep `auto` and the instruction, leave out `strict`, and validate the tool input in your code.
203217
204 If your application requires a specific tool call on the current turn, append a [mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) after the latest `user` turn. Name the tool, say that the call is required for this turn, and tell Claude to open its response with it. Earlier turns stay unchanged, so their prompt cache hits and thinking blocks stay valid. [Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) lists the platforms where they’re available. For a turn that must not call tools, `tool_choice: {"type": "none"}` still works. See [Forcing tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#forcing-tool-use).
218 If your application requires a specific tool call on the current turn, append a [mid-conversation system message](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) after the latest `user` turn. Name the tool, say that the call is required for this turn, and tell Claude to open its response with it. Earlier turns stay unchanged, so their prompt cache hits and thinking blocks stay valid. For the platforms where they’re available, see [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages). For a turn that must not call tools, `tool_choice: {"type": "none"}` still works. See [Forcing tool use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/define-tools#forcing-tool-use).
205219
2062. **Editing earlier turns invalidates thinking blocks, on every account:** Claude Fable 5 doesn’t check whether earlier turns changed. On Claude Fable 5.2, each `thinking` block is valid only against the `system` prompt, `tools`, and messages that came before it. Claude Fable 5.2 enforces this [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check) for every account. A request that sends a thinking block back after any of those changed returns a 400 error, and retrying the same request body doesn’t clear it.
2202. **Editing earlier turns invalidates thinking blocks:** On Claude Fable 5.2, each `thinking` block is valid only against the `system` prompt, `tools`, and messages that came before it. If any of those changed, a request sending the block back fails the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check) and gets a 400 error. Retrying the same request body doesn’t clear the error.
207221
208 Nothing changes for you if Claude Code, claude.ai, [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), or the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) manages your conversation history. If your code builds the `messages` array itself, keep the history append-only. Freeze `system` and `tools` for the session. Make instruction and tool changes with [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages), and trim context with server-side [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) or [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing). [Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) lists the platforms where they’re available. [Make changes without editing the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#replace-prefix-edits) gives the replacement for each common edit.
222 Nothing changes for you if Claude Code, claude.ai, [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), or the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) manages your conversation history. If your code builds the `messages` array itself, keep the history append-only. Freeze `system` and `tools` for the session. Make instruction and tool changes with [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages), and trim context with server-side [compaction](https://platform.claude.com/docs/en/build-with-claude/compaction) or [context editing](https://platform.claude.com/docs/en/build-with-claude/context-editing). For the platforms where mid-conversation system messages are available, see [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages). For what to send instead of each change, see [Change tools or instructions without failing the prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/change-tools-or-instructions).
209223
210 To find these edits before you switch production traffic, run the check in [Check whether your code edits the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#how-to-tell-whether-your-integration-is-impacted) against `claude-fable-5-2`. In production, leave `prefix_mismatch_behavior` at its default, `"error"`, if a mismatch can only mean a bug in your code. To drop the affected blocks and continue without that reasoning while you fix the edit, set it to `"drop_block"` with the `thinking-binding-controls-2026-08-01` beta header. Treat that as a stopgap, not a long-term setting: [dropping blocks can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost).
224 To find these edits before you switch production traffic, run the test in [Test your code for prefix check failures](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/fix-bound-to-a-different-conversation#how-to-tell-whether-your-integration-is-impacted) against `claude-fable-5-2`. In production, leave `prefix_mismatch_behavior` at its default, `"error"`, if a mismatch can only mean a bug in your code. To drop the affected blocks and continue without that reasoning while you fix the edit, set it to `"drop_block"` with the `thinking-binding-controls-2026-08-01` beta header. Treat that as a stopgap, not a long-term setting: [dropping blocks can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/fix-bound-to-a-different-conversation#drop-block-cost).
211225
2123. **Claude Fable 5 can’t read Claude Fable 5.2’s thinking blocks:** On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 reads Claude Fable 5’s blocks, so a conversation that moves from `claude-fable-5` onto `claude-fable-5-2` keeps its earlier reasoning. In the other direction, Claude Fable 5 can’t read Claude Fable 5.2’s blocks. If a router switch, a client-side retry, or a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) moves a conversation from Claude Fable 5.2 to another model, Claude Fable 5 included, the API drops the blocks that model can’t read. The request succeeds, and you aren’t billed for the dropped input tokens. With the `thinking-binding-controls-2026-08-01` beta header, `input_transformations` lists each dropped block with `reason: "model_binding_mismatch"`. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
2263. **Claude Fable 5 can’t read Claude Fable 5.2’s thinking blocks:** On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 reads Claude Fable 5’s blocks, so a conversation that moves from `claude-fable-5` onto `claude-fable-5-2` keeps its earlier reasoning. In the other direction, Claude Fable 5 can’t read Claude Fable 5.2’s blocks.
213227
2144. **Use the computer use toolset instead of `computer_20251124`:** On Claude Fable 5.2, a `tools` entry of type `computer_20251124` returns a 400 error on every platform except Amazon Bedrock. Claude Fable 5 accepts it with its beta header. Declare the `computer_toolset_20260801` toolset instead, as [Use the computer use toolset instead of `computer_20251124`](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-computer-use) describes.
228 If a router switch, a client-side retry, or a [classifier refusal fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback) moves a conversation from Claude Fable 5.2 to another model, Claude Fable 5 included, the API drops the blocks that model can’t read. The request succeeds, and you aren’t billed for the dropped input tokens. With the `thinking-binding-controls-2026-08-01` beta header, `input_transformations` lists each dropped block with `reason: "model_binding_mismatch"`. See [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
215229
2304. **Use the computer use toolset instead of `computer_20251124`:** On Claude Fable 5.2, a `tools` entry of type `computer_20251124` returns a 400 error on every platform except Amazon Bedrock. Claude Fable 5 accepts it with its beta header. Declare the `computer_toolset_20260801` toolset instead (see [Use the computer use toolset instead of `computer_20251124`](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-computer-use)).
231
2162325. **A Claude Fable 5.2 executor needs a Claude Fable 5.2 or Claude Mythos 5.2 advisor:** With the [advisor tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/advisor-tool), which is in beta, a Claude Fable 5.2 executor accepts only Claude Fable 5.2 or Claude Mythos 5.2 as its advisor. The other advisors a Claude Fable 5 executor accepts, such as Claude Fable 5 and Claude Opus 5.5, return a 400 error. Set the advisor’s `model` to `claude-fable-5-2` or `claude-mythos-5-2` when you change the executor’s. See [A Claude Fable 5.2 executor needs a Claude Fable 5.2 or Claude Mythos 5.2 advisor](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-advisor-pairs).
217233
218234### Other changes
from line 242
226242* Update the model name from `claude-fable-5` to `claude-fable-5-2`.
227243* Check your [rate limits](https://platform.claude.com/docs/en/api/rate-limits#rate-limits) before you move production traffic. Claude Fable 5.2 has its own rate limit, separate from the one Claude Fable 5.1 and Claude Fable 5 share.
228244* Replace forced `tool_choice` (`{type: "any"}` or `{type: "tool", ...}`) with `{type: "auto"}` plus an explicit instruction and `strict: true` tools, or with JSON outputs. Put the instruction in the `user` turn. When your application requires the call, put it in a mid-conversation `role: "system"` message instead, on the platforms that [Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) lists. In an organization with [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek), strict tool use and JSON outputs aren’t available for Claude Fable 5.2. There, keep `{type: "auto"}` and the instruction, and validate the tool input in your code.
229* If your code builds the `messages` array itself, run a session with the `thinking-binding-controls-2026-08-01` beta header and `prefix_mismatch_behavior: "drop_block"`, log `input_transformations`, and fix every `prefix_binding_mismatch` entry. `model_binding_mismatch` entries after a model switch are expected.
230* Keep the history append-only: freeze `system` and `tools` at session start, make mid-session changes with `role: "system"` messages, and trim context on the server. [Mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) lists the platforms where they’re available.
231* Pick a production `prefix_mismatch_behavior`: `"error"` (the default), or `"drop_block"` as a stopgap while you fix the edits, because [dropping blocks can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost). Monitor the 400 errors or the `input_transformations` entries.
245* If your code builds the `messages` array itself, run a session against `claude-fable-5-2` with the `thinking-binding-controls-2026-08-01` beta header and `prefix_mismatch_behavior: "drop_block"`, log `input_transformations`, and fix every `prefix_binding_mismatch` entry.
246* Keep the history append-only: freeze `system` and `tools` at session start, make mid-session changes with `role: "system"` messages, and trim context on the server. For the platforms where mid-conversation system messages are available, see [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages).
247* Pick a production `prefix_mismatch_behavior`: `"error"` (the default), or `"drop_block"` as a stopgap while you fix the edits, because [dropping blocks can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/fix-bound-to-a-different-conversation#drop-block-cost). Monitor the 400 errors or the `input_transformations` entries.
232248* Keep passing `thinking` blocks back unchanged on every turn, including empty ones. If a router or fallback can move a conversation from Claude Fable 5.2 to Claude Fable 5, expect Claude Fable 5 to run without Claude Fable 5.2’s blocks.
233* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Fable 5.2 thinking blocks that another account produced. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
249* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Fable 5.2 thinking blocks that another account produced. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
234250* If you use computer use through `computer_20251124` anywhere except Amazon Bedrock, Claude Fable 5.2 returns a 400 error for that tool. Declare `computer_toolset_20260801` instead and update your agent loop for the toolset.
235251* If you use the advisor tool with Claude Fable 5.2 as the executor, set the advisor’s `model` to `claude-fable-5-2` or `claude-mythos-5-2`.
236252* If you change effort between requests, move the change to a per-message effort `role: "system"` message, which is in beta, where your platform supports it.
from line 262
246262Four of the changes in [Migrating to Claude Fable 5.2 from Claude Fable 5](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#migrating-from-claude-fable-5-to-claude-fable-5-2) apply as written:
247263
248264* [Forced tool choice returns a 400 error](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-forced-tool-choice).
249* [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) (for every account).
265* [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history).
250266* [Use the computer use toolset instead of `computer_20251124`](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-computer-use).
251267* A Claude Fable 5.2 or Claude Mythos 5.2 executor [needs one of those two models as its advisor](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-advisor-pairs).
252268
253On the Claude API and Claude Models on Google Cloud (Google managed), Claude Mythos 5.2 reads Claude Mythos 5’s thinking blocks, so a conversation that moves from `claude-mythos-5` onto `claude-mythos-5-2` keeps its earlier reasoning. In the other direction, Claude Mythos 5 can’t read Claude Mythos 5.2’s blocks: the API drops them, and the request succeeds. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). Claude Mythos 5.2 costs $8 USD per million input tokens and $40 USD per million output tokens, compared with $10 USD and $50 USD on Claude Mythos 5. Prompt cache reads are $0.20 USD per million tokens, compared with $1 USD.
269On the Claude API and Claude Models on Google Cloud (Google managed), Claude Mythos 5.2 reads Claude Mythos 5’s thinking blocks, so a conversation that moves from `claude-mythos-5` onto `claude-mythos-5-2` keeps its earlier reasoning. In the other direction, Claude Mythos 5 can’t read Claude Mythos 5.2’s blocks: the API drops them, and the request succeeds. See [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
254270
271Claude Mythos 5.2 costs $8 USD per million input tokens and $40 USD per million output tokens, compared with $10 USD and $50 USD on Claude Mythos 5. Prompt cache reads are $0.20 USD per million tokens, compared with $1 USD.
272
255273### Update your model name
256274
257275```python
from line 284
266284* If you use computer use through `computer_20251124` anywhere except Amazon Bedrock, Claude Mythos 5.2 returns a 400 error for that tool. Declare `computer_toolset_20260801` instead and update your agent loop for the toolset.
267285* If you use the advisor tool with Claude Mythos 5.2 as the executor, set the advisor’s `model` to `claude-mythos-5-2` or `claude-fable-5-2`.
268286* Keep passing `thinking` blocks back unchanged on every turn, including empty ones.
269* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Mythos 5.2 thinking blocks that another account produced. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
270* If your code builds the `messages` array itself, run the check in [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) against `claude-mythos-5-2`, fix every `prefix_binding_mismatch` entry, and keep conversation history append-only (see [What counts as an edit](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#what-counts-as-an-edit)). An append-only history also keeps the prompt cache warm.
287* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Mythos 5.2 thinking blocks that another account produced. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
288* If your code builds the `messages` array itself, run the test in [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) against `claude-mythos-5-2`, fix every `prefix_binding_mismatch` entry, and keep conversation history append-only (see [What counts as a change](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#what-counts-as-an-edit)). An append-only history also keeps the prompt cache warm.
271289* Handle `stop_reason: "refusal"` and read `stop_details.category` before response content. See [Refusals and fallback](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback).
272290* Re-run your effort sweep, and re-baseline cost and latency.
273291* Check the system prompts, skills, and other instructions you carry over against [Review prompts and harnesses designed for earlier models](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#review-instructions-written-for-earlier-models).
from line 307
289307
2903082. **Forced tool choice returns a 400 error:** Claude Opus 5 accepts `tool_choice` `any` and `tool`. Claude Fable 5.2 rejects both. See [Forced tool choice returns a 400 error](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-forced-tool-choice) for what to send instead.
291309
2923. **Editing earlier turns invalidates thinking blocks, on every account:** Claude Opus 5 doesn’t check whether earlier turns changed. Claude Fable 5.2 does, for every account. If your code edits earlier messages, rebuilds `system` or `tools`, or compacts on the client between requests, Claude Fable 5.2 rejects the request or drops the invalid thinking blocks. See [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) for what to change and how to test.
3103. **Editing earlier turns invalidates thinking blocks:** If your code edits earlier messages, rebuilds `system` or `tools`, or compacts on the client between requests, the thinking blocks after the changed content become invalid. A later request that sends one back to Claude Fable 5.2 gets a 400 error, or, with `prefix_mismatch_behavior` set to `"drop_block"`, the API drops it. See [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) for what to change and how to test.
293311
2944. **Claude Opus 5 can’t read Claude Fable 5.2’s thinking blocks:** On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 reads Claude Opus 5’s blocks, so a conversation that moves from `claude-opus-5` onto `claude-fable-5-2` keeps its earlier reasoning. In the other direction, Claude Opus 5 can’t read Claude Fable 5.2’s blocks. A conversation that moves from Claude Fable 5.2 to Claude Opus 5 runs the turns after the switch without Claude Fable 5.2’s reasoning. The API drops those blocks before the model receives them, the request succeeds, and the dropped blocks aren’t billed. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
3124. **Claude Opus 5 can’t read Claude Fable 5.2’s thinking blocks:** On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 reads Claude Opus 5’s blocks, so a conversation that moves from `claude-opus-5` onto `claude-fable-5-2` keeps its earlier reasoning.
295313
314 In the other direction, Claude Opus 5 can’t read Claude Fable 5.2’s blocks. A conversation that moves from Claude Fable 5.2 to Claude Opus 5 runs the turns after the switch without Claude Fable 5.2’s reasoning. The API drops those blocks before the model receives them, the request succeeds, and the dropped blocks aren’t billed. See [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
315
2963165. **Text between tool calls is returned in thinking blocks:** On Claude Opus 5, text the model writes between tool calls comes back as `text` blocks. On Claude Fable 5.2, that narration comes back as progress-update `thinking` blocks, at most one before each tool call. If your interface renders that narration, set `thinking.display` to `"updates"`, which is in beta, to receive the progress updates as text while reasoning stays hidden, or to `"summarized"` to receive both. Then render the non-empty `thinking` blocks between `tool_use` blocks. See [Progress updates between tool calls](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates).
297317
2983186. **Use the computer use toolset instead of `computer_20251124`:** Claude Opus 5 accepts the earlier `computer_20251124` tool with its beta header. Claude Fable 5.2 returns a 400 error for it on every platform except Amazon Bedrock. See [Use the computer use toolset instead of `computer_20251124`](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-computer-use).
299319
3007. **Safety classifiers and fallback:** Claude Fable 5.2’s safety classifiers cover a broader set of `stop_details` categories than Claude Opus 5’s classifiers. Expect additional `stop_details.category` values, such as `"bio"`. Handle every category in the [refusal category table](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response). To re-run declined requests on another model, set `fallbacks: "default"` or build your own retry. That parameter is in beta on the Claude API and Claude Models on Google Cloud (Anthropic managed), and needs the `server-side-fallback-2026-07-01` beta header. [Refusals, fallback, and billing](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#refusals-fallback-and-billing) lists the permitted fallback targets.
3207. **Safety classifiers and fallback:** Claude Fable 5.2’s safety classifiers cover a broader set of `stop_details` categories than Claude Opus 5’s classifiers. Expect additional `stop_details.category` values, such as `"bio"`. Handle every category in the [refusal category table](https://platform.claude.com/docs/en/build-with-claude/refusals-and-fallback#refusal-response). To re-run declined requests on another model, set `fallbacks: "default"` or build your own retry. That parameter is in beta on the Claude API and Claude Models on Google Cloud (Anthropic managed), and needs the `server-side-fallback-2026-07-01` beta header. For the permitted fallback targets, see [Refusals, fallback, and billing](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#refusals-fallback-and-billing).
301321
3023228. **Pricing:** Claude Fable 5.2 costs $8 USD per million input tokens and $40 USD per million output tokens, compared with $5 USD and $25 USD for Claude Opus 5. Prompt cache reads are $0.20 USD per million tokens, compared with $0.50 USD. See [Pricing](https://platform.claude.com/docs/en/about-claude/pricing).
303323
from line 347
327347* Remove any `thinking: {type: "disabled"}` configuration. Control token spend with lower effort levels, revisit `max_tokens`, and select content blocks by `type`.
328348* Pass `thinking` blocks back unchanged on every turn, including empty ones. In a tool-use loop, send them back with the tool results. See [Preserving thinking blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#preserving-thinking-blocks).
329349* Replace forced `tool_choice` (`any` or `tool`) with `auto` plus an explicit instruction and `strict: true` tools, or with JSON outputs. In an organization with [customer-managed encryption keys](https://platform.claude.com/docs/en/manage-claude/cmek), strict tool use and JSON outputs aren’t available for Claude Fable 5.2. There, keep `auto` and the instruction, and validate the tool input in your code.
330* If your code builds the `messages` array itself, run the check in [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) against `claude-fable-5-2`, fix every `prefix_binding_mismatch` entry, and keep the history append-only.
350* If your code builds the `messages` array itself, run the test in [Editing earlier turns invalidates thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-edited-history) against `claude-fable-5-2`, fix every `prefix_binding_mismatch` entry, and keep the history append-only.
331351* If you use computer use through `computer_20251124` anywhere except Amazon Bedrock, Claude Fable 5.2 returns a 400 error for that tool. Declare `computer_toolset_20260801` instead and update your agent loop for the toolset.
332352* If you use the advisor tool with Claude Fable 5.2 as the executor, set the advisor’s `model` to `claude-fable-5-2` or `claude-mythos-5-2`.
333353* If a router or fallback moves conversations from Claude Fable 5.2 to Claude Opus 5, expect the turns after the switch to run without Claude Fable 5.2’s thinking blocks.
334* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Fable 5.2 thinking blocks that another account produced. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
354* If you replay stored conversations through a different account, replay each one through the account that produced it, or an account linked to it. The API drops Claude Fable 5.2 thinking blocks that another account produced. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
335355* If your interface renders text between tool calls, set `thinking.display` to `"updates"`, which is in beta, or to `"summarized"`, and render the non-empty `thinking` blocks.
336356* Handle every `stop_details.category`. If you set an explicit `fallbacks` list, name only Claude Fable 5.2’s permitted targets.
337357* If you use fast mode in Messages API requests on the Claude API, keep `speed: "fast"` only if [Availability of fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode#feature-availability) lists the model you move to. If you keep it, re-baseline cost against the [fast mode prices](https://platform.claude.com/docs/en/about-claude/pricing#fast-mode-pricing). Remove `speed: "fast"` in Claude Managed Agents. You don’t need the `fast-mode-2026-02-01` beta header, and requests that send it keep working.
models/fable-5-2/whats-new-fable-5-2 Changed · +19 / -19 lines
### Editing earlier turns invalidates thinking blocks ### Editing earlier turns invalidates thinking blocks on every account
from line 8
88
99Four changes from Claude Fable 5.1 can break your code:
1010
11* [The prefix check applies to every account](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#editing-earlier-turns-invalidates-thinking-blocks).
11* [Failed prefix checks return a 400 error](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#editing-earlier-turns-invalidates-thinking-blocks).
1212* [Only Claude Fable 5.2 and Claude Mythos 5.2 read Claude Fable 5.2 thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#thinking-blocks-are-tied-to-the-model-that-produced-them).
1313* The earlier [`computer_20251124` computer use tool returns an error](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#computer-20251124-is-not-supported) on every platform except Amazon Bedrock.
1414* With the advisor tool, a Claude Fable 5.2 executor [needs a Claude Fable 5.2 or Claude Mythos 5.2 advisor](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#advisor-tool-pairs).
from line 15
1515
1616## Models
1717
18| Model | Claude API ID | Description | Availability |
19| ----------------- | ----------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
20| Claude Fable 5.2 | claude-fable-5-2 | For demanding reasoning and long-horizon agentic work | All customers on the Claude API (see each platform’s page for partner platforms) |
21| Claude Mythos 5.2 | claude-mythos-5-2 | Same capabilities as Claude Fable 5.2 | Organizations verified through Anthropic’s verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842) |
18| Model | Claude API ID | Description | Availability |
19| ----------------- | ----------------- | ----------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
20| Claude Fable 5.2 | claude-fable-5-2 | For demanding reasoning and long-horizon agentic work | All customers on the Claude API (for other platforms, see [Availability](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#availability)) |
21| Claude Mythos 5.2 | claude-mythos-5-2 | Same capabilities as Claude Fable 5.2 | Organizations verified through Anthropic’s verification programs, such as the [Cyber Verification Program](https://support.claude.com/en/articles/14604842) |
2222
2323Claude Fable 5.2 and Claude Mythos 5.2 share these specs:
2424
from line 30
3030
3131## Breaking changes
3232
33### Editing earlier turns invalidates thinking blocks on every account
33### Editing earlier turns invalidates thinking blocks
3434
35The API’s prefix check (see [Keeping the prefix unchanged](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#prefix-check)) tests whether anything before a Claude Fable 5.2 or Claude Mythos 5.2 thinking block has changed since the model produced it: the `system` prompt, the `tools`, or an earlier message. On Claude Fable 5.2 and Claude Mythos 5.2, a request that sends back an invalid thinking block and leaves `prefix_mismatch_behavior` unset gets a 400 error, whatever the account’s age (see [When `prefix_mismatch_behavior` is unset](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#enforcement)). On Claude Fable 5.1, such a request gets the error on accounts created on or after August 31, 2026. On the Claude API, Claude Mythos 5.1 already returns it on every account. So code on Claude Fable 5.1 that edits its history can run without errors on an older account before the switch and fail after it.
35On Claude Fable 5.2 and Claude Mythos 5.2, a request that fails the API’s prefix check gets a [400 error](https://platform.claude.com/docs/en/api/errors#thinking-block-conversation-mismatch). The prefix check tests whether anything before a thinking block has changed since the model produced it. It covers the `system` prompt, the `tools`, and every earlier message (see [What must stay the same, and why](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check)). The error message says `The block is bound to a different conversation`.
3636
37When the check fails, the request returns a 400 error whose message says `The block is bound to a different conversation`. To drop the affected blocks and continue instead, send the `thinking-binding-controls-2026-08-01` beta header and set `thinking.block_binding.prefix_mismatch_behavior` to `"drop_block"`. The response then lists each dropped block in a top-level `input_transformations` array. Treat `"drop_block"` as a stopgap while you fix the edit, because [dropping blocks can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#drop-block-cost).
38
3937Nothing changes for you if Claude Code, claude.ai, [Claude Managed Agents](https://platform.claude.com/docs/en/managed-agents/overview), or the [Claude Agent SDK](https://code.claude.com/docs/en/agent-sdk/overview) builds your requests.
4038
4139If your own code builds your requests, nothing changes for you either, as long as all of these are true:
from line 40
4240
4341* Your code keeps `system` and `tools` the same for the whole conversation.
4442* Your code only adds to `messages`. It never changes, reorders, or removes an earlier message.
45* Your code [sends each assistant turn back exactly as the API returned it](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#append-assistant-turns-exactly-as-returned): every block, in the same order.
46* Your code does none of the things listed in [What to check in your integration](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#what-to-check).
43* Your code [sends each assistant turn back exactly as the API returned it](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/change-tools-or-instructions#append-assistant-turns-exactly-as-returned): every block, in the same order.
44* Your code does none of the things listed in [If your code changes the system prompt, tools, or history](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#what-to-check).
4745
4846Otherwise, test your code before you switch:
4947
from line 48
5048* **Code on Claude Fable 5.1:** Follow the [prefix check section](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-preserved-thinking) of the migration guide.
5149* **Code on Claude Mythos 5.1:** Follow [Migrating to Claude Mythos 5.2 from Claude Mythos 5.1](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#migrating-from-claude-mythos-5-1-to-claude-mythos-5-2).
5250
53[Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) explains what counts as an edit. It also shows how to make each change without an edit.
51For what counts as an edit, see [What counts as a change](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#what-counts-as-an-edit). To make each change without an edit, see [Change tools or instructions without failing the prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/change-tools-or-instructions).
5452
53To drop the affected thinking blocks and continue without the 400 error, send the `thinking-binding-controls-2026-08-01` beta header and set `thinking.block_binding.prefix_mismatch_behavior` to `"drop_block"`. The response then lists each dropped block in a top-level `input_transformations` array. Treat `"drop_block"` as a stopgap while you fix the edit, because [dropping blocks can raise output tokens](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/fix-bound-to-a-different-conversation#drop-block-cost).
54
5555### Only Claude Fable 5.2 and Claude Mythos 5.2 read Claude Fable 5.2 thinking blocks
5656
57Every thinking block records which model produced it, and a model reads only its own blocks and some other models’ blocks. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 read each other’s thinking blocks and those from Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5, Claude Fable 5, and Claude Mythos 5, and from earlier Opus, Sonnet, and Haiku models. No other model reads their blocks.
57Every thinking block records which model produced it, and a model reads only its own blocks and some other models’ blocks. On the Claude API and Claude Models on Google Cloud (Google managed), Claude Fable 5.2 and Claude Mythos 5.2 read each other’s thinking blocks. On those platforms, they also read blocks from Claude Opus 5.5, Claude Sonnet 5.5, Claude Haiku 5.5, Claude Fable 5.1, Claude Mythos 5.1, Claude Opus 5, Claude Fable 5, and Claude Mythos 5. They read blocks from [earlier Claude Opus, Claude Sonnet, and Claude Haiku models](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#earlier-models) too. No other model reads their blocks.
5858
5959* **Moving onto Claude Fable 5.2 or Claude Mythos 5.2** from one of those models keeps the conversation’s reasoning on the Claude API and Claude Models on Google Cloud (Google managed). So does moving between Claude Fable 5.2 and Claude Mythos 5.2.
6060* **Moving from Claude Fable 5.2 or Claude Mythos 5.2 to any other model** loses their reasoning for the turns that run there. That includes Claude Opus 5.5, Claude Fable 5.1, Claude Mythos 5.1, and Claude Fable 5.2’s fallback models (Claude Opus 4.8 and Claude Opus 5).
6161
62When a request carries a block the current model can’t read, the API drops the block before the model receives it. The request succeeds, and dropped blocks aren’t billed. With the `thinking-binding-controls-2026-08-01` beta header, the response lists the drop in `input_transformations`. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
62When a request carries a block the current model can’t read, the API drops the block before the model receives it. The request succeeds, and dropped blocks aren’t billed. With the `thinking-binding-controls-2026-08-01` beta header, the response lists the drop in `input_transformations`. See [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
6363
6464### Use the computer use toolset instead of `computer_20251124`
6565
from line 86
8686
8787* **Effort:** all five [effort levels](https://platform.claude.com/docs/en/build-with-claude/effort#effort-levels): `low`, `medium`, `high`, `xhigh`, and `max`. The API default is `high`. Start there, because most of the gain in capability is already present at `high`. Step up to `xhigh` for your hardest long-running coding and agentic work, where you’ve measured a gain. Reserve `max` for measuring the model’s ceiling and for the rare task where time and tokens don’t matter. See [Recommended effort levels for Claude Fable 5.2](https://platform.claude.com/docs/en/build-with-claude/effort#recommended-effort-levels-for-claude-fable-5-2).
8888* **Compaction on demand (beta):** with the `compact-2026-09-04` beta header, you choose when to replace older turns with a summary. See [Compaction on demand](https://platform.claude.com/docs/en/build-with-claude/compaction-on-demand).
89* **Mid-conversation tool changes (beta):** you add or remove tools in a `role: "system"` message instead of editing `tools`. On the Claude API, Claude Platform on AWS, and Claude Models on Google Cloud (Anthropic managed), send the `inline-tools-2026-09-15` beta header. The `mid-conversation-tool-changes-2026-07-01` header works for changes that name a tool by reference, on the platforms that [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) lists. See [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes).
89* **Mid-conversation tool changes (beta):** you add or remove tools in a `role: "system"` message instead of editing `tools`. On the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), and Microsoft Foundry, send the `inline-tools-2026-09-15` beta header. The `mid-conversation-tool-changes-2026-07-01` header works for changes that name a tool by reference, on the platforms that [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) lists. See [Mid-conversation tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#mid-conversation-tool-changes).
9090* **Computer use:** through the `computer_toolset_20260801` toolset. The earlier `computer_20251124` tool returns a 400 error on every platform except Amazon Bedrock. There, Claude Fable 5.2 and Claude Mythos 5.2 also accept the earlier tool. See the [computer use breaking change](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#computer-20251124-is-not-supported) and [Computer use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool).
9191
9292Compaction on demand and mid-conversation tool changes help you keep the history append-only, which the [prefix check](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#editing-earlier-turns-invalidates-thinking-blocks) requires. See each feature’s page for model and platform availability.
from line 97
9797
9898### Thinking blocks stay with the account that produced them
9999
100Thinking blocks that Claude Fable 5.2 and Claude Mythos 5.2 produce work only in the account that produced them, or in an account linked to it. When another account sends one of these blocks, the API drops the block before the model receives it, and the request succeeds. On the Claude API and Claude Models on Google Cloud (Google managed), with the `thinking-binding-controls-2026-08-01` beta header, the response lists each dropped block in `input_transformations` with `reason: "organization_binding_mismatch"`. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking) in Preserved thinking.
100Thinking blocks that Claude Fable 5.2 and Claude Mythos 5.2 produce work only in the account that produced them, or in an account linked to it. When another account sends one of these blocks, the API drops the block before the model receives it, and the request succeeds. On the Claude API and Claude Models on Google Cloud (Google managed), with the `thinking-binding-controls-2026-08-01` beta header, the response lists each dropped block in `input_transformations` with `reason: "organization_binding_mismatch"`. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking) in Preserved thinking.
101101
102102## Behavior differences
103103
104A few Claude Fable 5.2 behaviors show up without any code change. Check them when you carry prompts over. [Prompting Claude Fable 5.2](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2) has guidance for each:
104A few Claude Fable 5.2 behaviors show up without any code change. Check them when you carry prompts over. For guidance on each, see [Prompting Claude Fable 5.2](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2):
105105
106106* **Prompt lines that ask for less thinking don’t stop the model from thinking at `medium` effort and above.** Claude Fable 5.1 usually follows a line such as “answer directly without deliberating.” In Anthropic’s testing, such a line didn’t stop Claude Fable 5.2 from thinking at `medium` and above. At `high` and above, the model thinks before almost every reply. If easy requests take too long or cost too much, use a lower effort level for those turns. See [Calibrate effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#calibrate-effort).
107107* **A turn can end before the work is done.** On long, multistep tasks, the model sometimes ends a turn with a list of what remains, an offer to continue, or a stop at an ordinary obstacle. This occurs more often at `low` and `medium` effort. See [Finish the whole task](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-fable-5-2#finish-the-whole-task).
from line 200
200200
201201Then review these items:
202202
2031. **Check whether your code edits history.** If your code builds the `messages` array itself, run the test in the migration guide’s [prefix check section](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-preserved-thinking), even if Claude Fable 5.1 has never returned the error for your account.
2031. **Check whether your code edits history.** If your code builds the `messages` array itself, run the test in the migration guide’s [prefix check section](https://platform.claude.com/docs/en/models/fable-5-2/migration-guide#fable-5-2-preserved-thinking).
2042042. **Check model switches.** If a router or fallback moves conversations between models, expect every model except Claude Mythos 5.2 to drop Claude Fable 5.2’s thinking blocks, Claude Fable 5.1 and Claude Opus 5.5 included. See [Only Claude Fable 5.2 and Claude Mythos 5.2 read Claude Fable 5.2 thinking blocks](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#thinking-blocks-are-tied-to-the-model-that-produced-them).
2052053. **Move computer use to the toolset.** If you use the `computer_20251124` tool anywhere except Amazon Bedrock, Claude Fable 5.2 returns a 400 error for that tool. Declare `computer_toolset_20260801` instead. For the change itself, see [Use the computer use toolset instead of `computer_20251124`](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#computer-20251124-is-not-supported).
2062064. **Update the advisor.** If you use the advisor tool with Claude Fable 5.2 as the executor, set the advisor’s `model` to `claude-fable-5-2` or `claude-mythos-5-2`. See [A Claude Fable 5.2 executor needs a Claude Fable 5.2 or Claude Mythos 5.2 advisor](https://platform.claude.com/docs/en/models/fable-5-2/whats-new-fable-5-2#advisor-tool-pairs).
models/haiku-5-5/migration-guide Changed · +7 / -3 lines
from line 118
118118| From Claude Haiku 5.5, to Claude Opus 5.5, Claude Sonnet 5.5, Claude Fable 5.2, or Claude Mythos 5.2 | Yes, on the Claude API and Claude Models on Google Cloud (Google managed) only |
119119| From Claude Haiku 5.5, to any other model | No |
120120
121See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). For switches that don’t involve Claude Haiku 5.5, see [Which model switches keep the reasoning on the Claude API](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#which-model-switches-keep-reasoning).
121See [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). For switches that don’t involve Claude Haiku 5.5, see [Which model switches keep the reasoning on the Claude API](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#which-model-switches-keep-reasoning).
122122
123123## Remove sampling parameters
124124
from line 145
145145
146146## Replay thinking blocks through the account that produced them
147147
148Thinking blocks from Claude Haiku 5.5 work only in the account that produced them or in an account linked to it. When another account sends one of these blocks, the API drops the block before the model receives it, and the request succeeds without that reasoning. This affects code that stores conversations and replays them through a different account, for example a service that serves several customers from one conversation store. Replay each conversation through the account that produced it. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
148Thinking blocks from Claude Haiku 5.5 work only in the account that produced them or in an account linked to it. When another account sends one of these blocks, the API drops the block before the model receives it, and the request succeeds without that reasoning. This affects code that stores conversations and replays them through a different account, for example a service that serves several customers from one conversation store. Replay each conversation through the account that produced it. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
149149
150150## Keep earlier turns unchanged
151151
152A Claude Haiku 5.5 thinking block stays valid only while everything sent before it is unchanged: the `system` prompt, the `tools`, and every earlier message. Claude Haiku 4.5 doesn’t run the prefix check. Keep conversations append-only. A request that sends a block back after such a change, with `thinking.block_binding.prefix_mismatch_behavior` unset, gets a 400 error. This applies to accounts created on or after August 31, 2026, 00:00 UTC. On accounts created before that date, the request might or might not get the error. For the changes that trigger the error and what to do instead, see [Who the prefix check affects](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#who-is-affected).
152Keep conversations append-only. A Claude Haiku 5.5 thinking block stays valid only while everything sent before it is unchanged: the `system` prompt, the `tools`, and every earlier message.
153
154Failing the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check) might or might not result in a [400 error](https://platform.claude.com/docs/en/api/errors#thinking-block-conversation-mismatch). To identify and handle both cases, see [Prefix checks on thinking blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks).
155
156For the changes that trigger the error and what to do instead, see [If your code changes the system prompt, tools, or history](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#what-to-check).
153157
154158## Migrating to Claude Haiku 5.5 from Claude Haiku 3.5 and earlier Haiku models
155159
models/opus-5-5/migration-guide Changed · +67 / -52 lines
from line 121
121121 };
122122
123123 var message = await client.Messages.Create(parameters);
124 Console.WriteLine(message);
124 foreach (var block in message.Content)
125 {
126 if (block.TryPickText(out var textBlock))
127 {
128 Console.WriteLine(textBlock.Text);
129 }
130 }
125131 ```
126132
127133 ```go Go
from line 282
276282* Set `effort` explicitly: the default is `medium`, where Claude Opus 5’s is `high`.
277283* Replace `tool_choice` types `any` and `tool` with `auto` plus strict tool use or structured outputs.
278284* If you use an earlier computer use tool version, declare `computer_toolset_20260801` instead, drop that version’s beta header, and update your agent loop for the toolset. On Amazon Bedrock, `computer_20251124` also works. See the [computer use breaking change](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#computer-use-toolset).
279* If a router or fallback can move a conversation off Claude Opus 5.5, expect the new model to run without Claude Opus 5.5’s thinking blocks. Claude Fable 5.1 and Claude Mythos 5.1 keep them on the Claude API. Claude Fable 5.2 and Claude Mythos 5.2 keep them on the Claude API and Claude Models on Google Cloud (Google managed). Claude Opus 5.5 itself reads thinking from Claude Opus 5 and from earlier Opus, Sonnet, and Haiku models. On the Claude API and Claude Models on Google Cloud (Google managed), it also reads thinking from Claude Sonnet 5.5 and Claude Haiku 5.5. It doesn’t read thinking from Claude Fable or Claude Mythos models.
285* If a router or fallback can move a conversation off Claude Opus 5.5, expect the new model to run without Claude Opus 5.5’s thinking blocks. Claude Fable 5.1 and Claude Mythos 5.1 keep them on the Claude API. Claude Fable 5.2 and Claude Mythos 5.2 keep them on the Claude API and Claude Models on Google Cloud (Google managed). Claude Opus 5.5 itself reads thinking from Claude Opus 5 and from [earlier Claude Opus, Claude Sonnet, and Claude Haiku models](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#earlier-models). On the Claude API and Claude Models on Google Cloud (Google managed), it also reads thinking from Claude Sonnet 5.5 and Claude Haiku 5.5. It doesn’t read thinking from Claude Fable or Claude Mythos models.
280286* Read content blocks by `type`, and pass `thinking` blocks back unmodified in tool-use loops.
281287* If your interface renders text between tool calls, set `display: "updates"` (in beta) or `"summarized"` and render the non-empty `thinking` blocks.
282288* If your code edits earlier turns, the `system` prompt, or `tools` mid-conversation, follow [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking).
from line 303
297303
298304* Run a fresh [effort](https://platform.claude.com/docs/en/build-with-claude/effort) sweep on your own evals rather than carrying over a setting tuned for an earlier model.
299305* Remove any context-window beta header.
300* If you rebuild conversation history to update instructions, consider switching to a mid-conversation system message to preserve prompt cache hits.
306* If you rebuild conversation history to update instructions, switch to a mid-conversation system message. After a rebuild, a request can get a 400 error, and prompt cache hits are lost.
301307* Verify your stop-reason handling reads `stop_details` on refusals.
302308* If you want fast mode, which Claude Opus 4.7 rejects, set `speed: "fast"` on your Claude API requests.
303309
from line 341
335341
336342### Claude Sonnet 5 only
337343
338* If you rebuild conversation history to update instructions, consider switching to a mid-conversation system message to preserve prompt cache hits.
344* If you rebuild conversation history to update instructions, switch to a mid-conversation system message. After a rebuild, a request can get a 400 error, and prompt cache hits are lost.
339345* Review prompts near the caching minimum: prompts of 512 tokens or more can create cache entries.
340346
341347## Migrating to Claude Opus 5.5 from Claude Opus 5
from line 617
611617 name: get_weather
612618 messages:
613619 - role: user
614 content: What's the weather in Paris?
620 content: What is the weather in Paris?
615621 YAML
616622 ```
617623
from line 627
621627 max_tokens=1024,
622628 tools=tools,
623629 tool_choice={"type": "tool", "name": "get_weather"},
624 messages=[{"role": "user", "content": "What's the weather in Paris?"}],
630 messages=[{"role": "user", "content": "What is the weather in Paris?"}],
625631 )
626632 ```
627633
from line 637
631637 max_tokens: 1024,
632638 tools,
633639 tool_choice: { type: "tool", name: "get_weather" },
634 messages: [{ role: "user", content: "What's the weather in Paris?" }]
640 messages: [{ role: "user", content: "What is the weather in Paris?" }]
635641 });
636642 ```
637643
from line 648
642648 MaxTokens = 1024,
643649 Tools = [.. tools],
644650 ToolChoice = new ToolChoiceTool { Name = "get_weather" },
645 Messages = [new UserMessageParam { Content = "What's the weather in Paris?" }],
651 Messages = [new UserMessageParam { Content = "What is the weather in Paris?" }],
646652 });
647653 ```
648654
from line 659
653659 Tools: tools,
654660 ToolChoice: anthropic.ToolChoiceParamOfTool("get_weather"),
655661 Messages: []anthropic.MessageParam{
656 anthropic.NewUserMessage(anthropic.NewTextBlock("What's the weather in Paris?")),
662 anthropic.NewUserMessage(anthropic.NewTextBlock("What is the weather in Paris?")),
657663 },
658664 })
659665 ```
from line 670
664670 .maxTokens(1024L)
665671 .tools(tools)
666672 .toolChoice(ToolChoiceTool.of("get_weather"))
667 .addUserMessage("What's the weather in Paris?")
673 .addUserMessage("What is the weather in Paris?")
668674 .build();
669675
670676 client.messages().create(params);
from line 682
676682 maxTokens: 1024,
677683 tools: $tools,
678684 toolChoice: ToolChoiceTool::with(name: 'get_weather'),
679 messages: [['role' => 'user', 'content' => "What's the weather in Paris?"]],
685 messages: [['role' => 'user', 'content' => 'What is the weather in Paris?']],
680686 );
681687 ```
682688
from line 692
686692 max_tokens: 1024,
687693 tools: tools,
688694 tool_choice: Anthropic::ToolChoiceTool.new(name: "get_weather"),
689 messages: [{ role: "user", content: "What's the weather in Paris?" }]
695 messages: [{ role: "user", content: "What is the weather in Paris?" }]
690696 )
691697 ```
692698</CodeGroup>
from line 754
748754 type: auto
749755 messages:
750756 - role: user
751 content: What's the weather in Paris? Use the get_weather tool.
757 content: What is the weather in Paris? Use the get_weather tool.
752758 YAML
753759 ```
754760
from line 768
762768 messages=[
763769 {
764770 "role": "user",
765 "content": "What's the weather in Paris? Use the get_weather tool.",
771 "content": "What is the weather in Paris? Use the get_weather tool.",
766772 }
767773 ],
768774 )
from line 784
778784 messages: [
779785 {
780786 role: "user",
781 content: "What's the weather in Paris? Use the get_weather tool."
787 content: "What is the weather in Paris? Use the get_weather tool."
782788 }
783789 ]
784790 });
from line 800
794800 ToolChoice = new ToolChoiceAuto(),
795801 Messages =
796802 [
797 new UserMessageParam { Content = "What's the weather in Paris? Use the get_weather tool." },
803 new UserMessageParam { Content = "What is the weather in Paris? Use the get_weather tool." },
798804 ],
799805 });
800806 ```
from line 820
814820 ToolChoice: anthropic.ToolChoiceUnionParam{OfAuto: &anthropic.ToolChoiceAutoParam{}},
815821 Messages: []anthropic.MessageParam{
816822 anthropic.NewUserMessage(
817 anthropic.NewTextBlock("What's the weather in Paris? Use the get_weather tool."),
823 anthropic.NewTextBlock("What is the weather in Paris? Use the get_weather tool."),
818824 ),
819825 },
820826 })
from line 840
834840 .orElse(tool))
835841 .toList())
836842 .toolChoice(ToolChoiceAuto.builder().build())
837 .addUserMessage("What's the weather in Paris? Use the get_weather tool.")
843 .addUserMessage("What is the weather in Paris? Use the get_weather tool.")
838844 .build();
839845
840846 client.messages().create(params);
from line 856
850856 messages: [
851857 [
852858 'role' => 'user',
853 'content' => "What's the weather in Paris? Use the get_weather tool.",
859 'content' => 'What is the weather in Paris? Use the get_weather tool.',
854860 ],
855861 ],
856862 );
from line 870
864870 tools: tools.map { |tool| tool.merge(strict: true) },
865871 tool_choice: Anthropic::ToolChoiceAuto.new,
866872 messages: [
867 { role: "user", content: "What's the weather in Paris? Use the get_weather tool." }
873 { role: "user", content: "What is the weather in Paris? Use the get_weather tool." }
868874 ]
869875 )
870876 ```
from line 878
872878
873879#### Thinking blocks are tied to the model and the conversation
874880
875Claude Fable 5.1 and Claude Mythos 5.1 read Claude Opus 5.5 thinking blocks on the Claude API. Claude Fable 5.2 and Claude Mythos 5.2 read them on the Claude API and Claude Models on Google Cloud (Google managed). No other model does. A router or fallback that moves a conversation from Claude Opus 5.5 to any other model runs those turns without them.
881Keep the conversation append-only (no edits to the `system` prompt, `tools`, or earlier messages mid-conversation) so the thinking blocks pass the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check). Claude Code, claude.ai, Claude Managed Agents, and the Claude Agent SDK do this. There is no code change for append-only integrations.
876882
877In the other direction, Claude Opus 5.5 reads thinking blocks from Claude Opus 5 and from earlier Opus, Sonnet, and Haiku models. On the Claude API and Claude Models on Google Cloud (Google managed), it also reads them from Claude Sonnet 5.5 and Claude Haiku 5.5. It doesn’t read them from Claude Fable or Claude Mythos models.
883Failing the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check) might or might not result in a [400 error](https://platform.claude.com/docs/en/api/errors#thinking-block-conversation-mismatch). To identify and handle both cases, see [Prefix checks on thinking blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks).
878884
879Keep the conversation append-only (no edits to the `system` prompt, `tools`, or earlier messages mid-conversation) so the blocks stay valid. Claude Code, claude.ai, Claude Managed Agents, and the Claude Agent SDK already do. If a request replays a thinking block after such an edit, with `thinking.block_binding.prefix_mismatch_behavior` unset, it gets a 400 error. This applies to accounts created on or after August 31, 2026, 00:00 UTC. [Preserved thinking availability](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#feature-availability) lists the platforms where this applies. There is no code change for append-only integrations. See [Thinking blocks are tied to the model and the conversation](https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5#thinking-blocks-are-tied-to-the-model-that-produced-them) and [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking).
885[Preserved thinking availability](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#feature-availability) lists the platforms where this applies.
880886
887Every thinking block also records which model produced it. A router or fallback can move a conversation from Claude Opus 5.5 to a model that doesn’t read Claude Opus 5.5 thinking blocks. The API drops those blocks before that model sees them, and the request succeeds. For which models read which blocks, see [Thinking blocks are tied to the model and the conversation](https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5#thinking-blocks-are-tied-to-the-model-that-produced-them) in What’s new in Claude Opus 5.5. See also [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking).
888
881889#### Some computer use tool versions are not supported
882890
883891Claude Opus 5.5 supports computer use through the `computer_toolset_20260801` toolset. On Amazon Bedrock, Claude Opus 5.5 also accepts the `computer_20251124` tool with the `computer-use-2025-11-24` beta header. Claude Opus 5.5 returns a 400 error for any computer use tool version it doesn’t accept, such as `computer_20251124` on the Claude API. It doesn’t accept `computer_20250124` on any platform. On the Claude API, the error message begins `'claude-opus-5-5' does not support tool types: computer_20251124.` and then lists the tool types the model accepts.
from line 1159
11511159
11521160### Recommended changes
11531161
11541. **Re-run your effort sweep.** Effort is the only thinking control on Claude Opus 5.5, and its default is `medium` where Claude Opus 5’s is `high`, so a request that omits `effort` runs at `medium`. Step down where quality holds, and step up for the most demanding work. See [Effort](https://platform.claude.com/docs/en/build-with-claude/effort).
11621. **Re-run your effort sweep.** Effort is the only request parameter that controls thinking depth on Claude Opus 5.5. The default is `medium`. Claude Opus 5’s is `high`, so a request that omits `effort` runs one level lower than it did on Claude Opus 5. Step down where quality holds, and step up for the most demanding work. See [Effort](https://platform.claude.com/docs/en/build-with-claude/effort).
115511632. **Re-evaluate model-specific prompt instructions.** Instructions tuned for Claude Opus 5’s behavior might no longer be needed; see [Prompting Claude Opus 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5). If you ran with thinking disabled, also see [Prompts written for thinking disabled](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#prompts-written-for-thinking-disabled).
115611643. **Test in a development environment** before switching production traffic.
11571165
11581166## Migrating to Claude Opus 5.5 from Claude Opus 4.8
11591167
1160First work through [What every request to Claude Opus 5.5 must satisfy](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#request-requirements), [Handle thinking in every response](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#thinking-in-every-response), and [Migrating to Claude Opus 5.5 from Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5). Use `claude-opus-4-8` as the model ID you replace. That last section applies to code on Claude Opus 4.8 as written, because Claude Opus 4.8, like Claude Opus 5:
1168First work through [What every request to Claude Opus 5.5 must satisfy](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#request-requirements), [Handle thinking in every response](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#thinking-in-every-response), and [Migrating to Claude Opus 5.5 from Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), with `claude-opus-4-8` as the model ID you replace. Everything in the Claude Opus 5 section also applies to you, because Claude Opus 4.8, like Claude Opus 5:
11611169
11621170* Accepts `thinking: {"type": "disabled"}`, forced tool choice, and the `computer_20251124` tool.
11631171* Returns the text between tool calls as `text` blocks.
11641172* Defaults to `high` effort.
11651173
1166This section adds what changed between Claude Opus 4.8 and Claude Opus 5. For a checklist, see the first two groups of the [migration checklist](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migration-checklist).
1174Then read [What changed](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#what-changed-from-claude-opus-4-8), which lists what took effect between Claude Opus 4.8 and Claude Opus 5. For a checklist, see the first two groups of the [migration checklist](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migration-checklist).
11671175
11681176### What changed
11691177
from line 1187
11791187
118011881. **Consider task budgets (beta):** For agentic workloads, [task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets) tell the model how many tokens it has for a full agentic loop. They require the `task-budgets-2026-03-13` beta header.
11811189
11822. **Consider mid-conversation tool changes (beta):** Mid-conversation tool changes let you add or remove tools between turns of a conversation without invalidating [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits on earlier turns. Changing the `tools` array itself invalidates the cached prefix. On the Claude API, Claude Platform on AWS, and Claude Models on Google Cloud (Anthropic managed), send the `inline-tools-2026-09-15` beta header. The `mid-conversation-tool-changes-2026-07-01` header works for changes that name a tool by reference, on the Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), and Claude Models on Google Cloud (Google managed).
11902. **Consider mid-conversation tool changes (beta):** These let you add or remove tools between turns with a `role: "system"` message and keep [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits on earlier turns. Changing the `tools` array loses those hits. Two beta headers enable mid-conversation tool changes. Where both work on your platform, send `inline-tools-2026-09-15`:
11831191
1192 * `inline-tools-2026-09-15` works on the Claude API, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), and Microsoft Foundry.
1193 * `mid-conversation-tool-changes-2026-07-01` works on Claude Models on Google Cloud (Google managed) and Amazon Bedrock, and on the four platforms listed for `inline-tools-2026-09-15`. It doesn’t cover [defining a tool inside a `tool_addition` block](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#define-tools-in-a-message-beta).
1194
11841195## Migrating to Claude Opus 5.5 from Claude Opus 4.7
11851196
1186First work through [What every request to Claude Opus 5.5 must satisfy](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#request-requirements), [Handle thinking in every response](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#thinking-in-every-response), [Migrating to Claude Opus 5.5 from Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), and [Migrating to Claude Opus 5.5 from Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8). Use `claude-opus-4-7` as the model ID you replace. Those sections apply to code on Claude Opus 4.7 as written. Like Claude Opus 4.8, it accepts `thinking: {"type": "disabled"}`, forced tool choice, and the `computer_20251124` tool. It defaults to `high` effort and runs without thinking unless you ask for it.
1197First work through [What every request to Claude Opus 5.5 must satisfy](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#request-requirements), [Handle thinking in every response](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#thinking-in-every-response), [Migrating to Claude Opus 5.5 from Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), and [Migrating to Claude Opus 5.5 from Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8), with `claude-opus-4-7` as the model ID you replace. They all apply to you as well: like Claude Opus 4.8, Claude Opus 4.7 accepts `thinking: {"type": "disabled"}`, forced tool choice, and the `computer_20251124` tool. It defaults to `high` effort and runs without thinking unless you ask for it.
11871198
1188This section adds what changed after Claude Opus 4.7. If your code is on Claude Opus 4.6 or earlier, continue with [Migrating to Claude Opus 5.5 from Claude Opus 4.6 and earlier Opus models](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-46) after this section. It adds the breaking changes that took effect in Claude Opus 4.7. For a checklist, see the first three groups of the [migration checklist](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migration-checklist).
1199Then check the following items. If your code is on Claude Opus 4.6 or earlier, continue with [Migrating to Claude Opus 5.5 from Claude Opus 4.6 and earlier Opus models](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-46). It has the breaking changes that took effect in Claude Opus 4.7. For a checklist, see the first three groups of the [migration checklist](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migration-checklist).
11891200
11901201### What changed
11911202
1192None of these items adds a breaking change to those in the earlier sections; they are worth checking after you swap the model ID.
1203These items add no breaking changes beyond those in the earlier sections. Check them after you swap the model ID.
11931204
11941. **Effort levels recalibrated:** The token allocation behind each effort level changes on Claude Opus 5.5 compared to Claude Opus 4.7. The default is `medium`, where Claude Opus 4.7’s is `high`. Run a fresh effort sweep on your own evals rather than carrying over a setting tuned for Claude Opus 4.7. See [Effort](https://platform.claude.com/docs/en/build-with-claude/effort).
12051. **Effort levels recalibrated:** Each effort level allocates tokens differently on Claude Opus 5.5 than on Claude Opus 4.7. The default is `medium`, where Claude Opus 4.7’s is `high`. Run a fresh effort sweep on your own evals rather than carrying over a setting tuned for Claude Opus 4.7. See [Effort](https://platform.claude.com/docs/en/build-with-claude/effort).
11951206
119612072. **1M context window is the default:** Claude Opus 5.5 serves the full 1M token [context window](https://platform.claude.com/docs/en/build-with-claude/context-windows) by default. If your client passes a context-window beta header for compatibility with older models, remove it.
11971208
11983. **Mid-conversation system messages:** On the Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), and Claude Models on Google Cloud (Google managed), Claude Opus 5.5 accepts `role: "system"` messages immediately after a user turn in the `messages` array (subject to [placement rules](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)). Use the top-level `system` field for instructions that apply from the start. Claude Opus 4.7 rejects `role: "system"` in `messages` with a 400 error. If you maintain code paths that rebuild the full message history to update instructions, you can simplify them and preserve [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits on earlier turns.
12093. **Mid-conversation system messages:** On [supported platforms](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#feature-availability), Claude Opus 5.5 accepts `role: "system"` messages immediately after a user turn in the `messages` array (subject to [placement rules](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)). Use the top-level `system` field for instructions that apply from the start. Claude Opus 4.7 rejects `role: "system"` in `messages` with a 400 error. If you maintain code paths that rebuild the full message history to update instructions, switch them to system messages. After a rebuild, a request can get a 400 error, and [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits are lost.
11991210
12004. **Refusal stop details:** When the model declines a request, Claude Opus 5.5 returns a `stop_details` object that names the category of refusal, alongside the `refusal` stop reason. Claude Opus 4.7 returns the same object, so this matters only if your stop-reason handling does not read it yet; if so, see [Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons). There is no opt-out. Claude Opus 5.5 declines in more categories; see [Safety classifiers and fallback](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#safety-classifiers-and-fallback).
12114. **Refusal stop details:** When the model declines a request, Claude Opus 5.5 returns a `stop_details` object that names the category of refusal, alongside the `refusal` stop reason. You can’t turn it off. Claude Opus 4.7 returns the same object, so there’s nothing to change if your stop-reason handling already reads it. If it doesn’t, see [Stop reasons and fallback](https://platform.claude.com/docs/en/build-with-claude/handling-stop-reasons). Claude Opus 5.5 declines in more categories; see [Safety classifiers and fallback](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#safety-classifiers-and-fallback).
12011212
12025. **Fast mode:** Claude Opus 5.5 supports [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) on the Claude API. Fast mode is not available on Claude Opus 4.7, where requests with `speed: "fast"` return an error. Set `speed: "fast"` on your requests.
12135. **Fast mode:** Claude Opus 5.5 supports [fast mode](https://platform.claude.com/docs/en/build-with-claude/fast-mode) on the Claude API and on [some cloud platforms](https://platform.claude.com/docs/en/build-with-claude/fast-mode#feature-availability). Fast mode is not available on Claude Opus 4.7, where requests with `speed: "fast"` return an error. To use it on the Claude API, set `speed: "fast"` on your requests.
12031214
120412156. **Computer use toolset and browser use tool:** Claude Opus 5.5 supports [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) as the `computer_toolset_20260801` toolset and the [browser use tool](https://platform.claude.com/docs/en/agents-and-tools/tool-use/browser-use-tool) for tasks inside webpages. Claude Opus 4.7 supports neither. To move a `computer_20251124` integration to the toolset, see the [computer use breaking change](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#computer-use-toolset).
12051216
12061217## Migrating to Claude Opus 5.5 from Claude Opus 4.6 and earlier Opus models
12071218
1208First work through every earlier section, in page order. They are [What every request to Claude Opus 5.5 must satisfy](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#request-requirements), [Handle thinking in every response](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#thinking-in-every-response), and the sections for [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8), and [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-47). Those sections apply to code on Claude Opus 4.6 as written. Like Claude Opus 4.7, it accepts `thinking: {"type": "disabled"}`, forced tool choice, and the `computer_20251124` tool. It defaults to `high` effort and runs without thinking unless you ask for it. Claude Opus 4.5 and earlier Opus models also accept `thinking: {"type": "disabled"}` and forced tool choice, and run without thinking unless you ask for it, so those sections apply to them too.
1219First work through every earlier section, in page order: [What every request to Claude Opus 5.5 must satisfy](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#request-requirements), [Handle thinking in every response](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#thinking-in-every-response), and the sections for [Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), [Claude Opus 4.8](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-4-8), and [Claude Opus 4.7](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-47). They all apply to you as well, because Claude Opus 4.6 and earlier Opus models accept `thinking: {"type": "disabled"}` and forced tool choice and run without thinking unless you ask for it. Claude Opus 4.6 also accepts the `computer_20251124` tool and defaults to `high` effort.
12091220
1210This section adds what changed in Claude Opus 4.7, with `claude-opus-4-6` as the model ID you replace. Its two subsections add what changed before that, for readers on [Claude Opus 4.5 or earlier](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-45) and [Claude 4.1 or earlier](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier). For a checklist, see the [migration checklist](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migration-checklist) up to the group that names your model.
1221Then apply the following changes, which took effect in Claude Opus 4.7. The model ID you replace is `claude-opus-4-6`. The two subsections add earlier changes, for readers on [Claude Opus 4.5 or earlier](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-45) and [Claude 4.1 or earlier](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier). For a checklist, see the [migration checklist](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migration-checklist) and stop after the group that names your model.
12111222
12121223### Breaking changes
12131224
from line 1534
15231534
15241535### Migrating from Claude Opus 4.5 or earlier
15251536
1526If you are migrating from Claude Opus 4.5, Claude Opus 4.1, or an earlier model directly to Claude Opus 5.5, read this page from the top: first work through every earlier section, in page order. Then work through the [breaking changes for migrating from Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#opus-46-breaking-changes) earlier in this section. Then apply the following cumulative changes, which took effect between Claude Opus 4.5 and Claude Opus 4.7. If you are on Claude Opus 4.1 or earlier, continue with [Migrating from Claude 4.1 or earlier](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier) after this subsection.
1537To migrate from Claude Opus 4.5, Claude Opus 4.1, or an earlier model directly to Claude Opus 5.5:
15271538
15391. Work through this page from the top, in page order, up to this subsection. That includes the [breaking changes for migrating from Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#opus-46-breaking-changes).
15402. Apply the changes in this subsection, which took effect between Claude Opus 4.5 and Claude Opus 4.7.
15413. If you’re on Claude Opus 4.1 or earlier, continue with [Migrating from Claude 4.1 or earlier](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-4-1-or-earlier).
1542
15281543#### Breaking changes
15291544
153015451. **Prefill removal** is covered in the [breaking changes for migrating from Claude Opus 4.6](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#opus-46-breaking-changes).
from line 1558
15431558
154415594. **Remove interleaved thinking beta header:** With adaptive thinking, interleaved thinking is automatic on every model that supports adaptive thinking. Remove the `interleaved-thinking-2025-05-14` beta from your requests.
15451560
15465. **Migrate to output\_config.format:** If using structured outputs, update `output_format={...}` to `output_config={"format": {...}}`. The `output_format` parameter is deprecated and will be removed in the future. To use it anyway, add the `structured-outputs-2025-11-13` beta header. Without it, the API returns a 400 error. The Python SDK (v1.0 and later) does not accept `output_format={...}` on `client.beta.messages.create()` or `count_tokens()`. The `output_format=Model` argument of the `parse()` and `stream()` helpers is unchanged.
15615. **Migrate to `output_config.format`:** If you use structured outputs, update `output_format={...}` to `output_config={"format": {...}}`. The `output_format` parameter is deprecated and will be removed in the future. To use it anyway, add the `structured-outputs-2025-11-13` beta header. Without it, the API returns a 400 error. In the Python SDK (v1.0 and later), a schema dictionary passed as `output_format={...}` raises a `TypeError`, so use `output_config`. A Pydantic model passed as `output_format=Model` to `parse()` or `stream()` works with no change and no beta header, because the SDK sends it as `output_config`.
15471562
15481563### Migrating from Claude 4.1 or earlier
15491564
from line 1714
16991714
170017154. **Handle the `model_context_window_exceeded` stop reason**
17011716
1702 Claude 4.5 and later models return a `model_context_window_exceeded` stop reason when generation stops because of hitting the context window limit, rather than the requested `max_tokens` limit. Update your application to handle this new stop reason:
1717 Claude 4.5 and later models return a `model_context_window_exceeded` stop reason when generation stops at the context window limit rather than at the requested `max_tokens` limit. Update your application to handle this stop reason:
17031718
17041719 <CodeGroup exclude="shell">
17051720 ```python Python
from line 1786
17711786
17721787#### Additional recommended changes
17731788
1774* **Beta headers:** Remove `token-efficient-tools-2025-02-19` and `output-128k-2025-02-19`. All Claude 4 and later models have built-in token-efficient tool use and these headers have no effect.
1789* **Beta headers:** Remove `token-efficient-tools-2025-02-19` and `output-128k-2025-02-19`. All Claude 4 and later models have built-in token-efficient tool use, and these headers have no effect.
17751790
17761791## Migrating to Claude Opus 5.5 from Claude Sonnet 5
17771792
1778Work through [What every request to Claude Opus 5.5 must satisfy](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#request-requirements), [Handle thinking in every response](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#thinking-in-every-response), and [Migrating to Claude Opus 5.5 from Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5). Use `claude-sonnet-5` as the model ID you replace. That last section applies to code on Claude Sonnet 5 as written, because Claude Sonnet 5, like Claude Opus 5:
1793Work through [What every request to Claude Opus 5.5 must satisfy](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#request-requirements), [Handle thinking in every response](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#thinking-in-every-response), and [Migrating to Claude Opus 5.5 from Claude Opus 5](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#migrating-from-claude-opus-5), with `claude-sonnet-5` as the model ID you replace. Everything in the Claude Opus 5 section also applies to you, because Claude Sonnet 5, like Claude Opus 5:
17791794
1780* Runs with thinking on by default and accepts `thinking: {"type": "disabled"}`, in its case at any effort level.
1795* Runs with thinking on by default and accepts `thinking: {"type": "disabled"}`. Unlike Claude Opus 5, it accepts this at any effort level.
17811796* Accepts forced tool choice and the `computer_20251124` tool.
17821797* Returns the text between tool calls as `text` blocks.
17831798* Defaults to `high` effort.
17841799
1785Manual extended thinking, sampling parameters, and assistant prefill return a 400 error on both models, so nothing changes there. None of the required changes in the sections for Claude Opus 4.8, Claude Opus 4.7, and Claude Opus 4.6 apply to you.
1800Manual extended thinking, sampling parameters, and assistant prefill return a 400 error on both Claude Sonnet 5 and Claude Opus 5.5, so nothing changes there. None of the required changes in the sections for Claude Opus 4.8, Claude Opus 4.7, and Claude Opus 4.6 apply to you.
17861801
17871802### What changed
17881803
17891. **Mid-conversation system messages:** On the Claude API, Amazon Bedrock, Claude Platform on AWS, Claude Models on Google Cloud (Anthropic managed), and Claude Models on Google Cloud (Google managed), Claude Opus 5.5 accepts `role: "system"` messages immediately after a user turn in the `messages` array (subject to [placement rules](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)). This feature is not available on Claude Sonnet 5. If you maintain code paths that rebuild the full message history to update instructions, you can simplify them and preserve [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits on earlier turns.
18041. **Mid-conversation system messages:** On [supported platforms](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#feature-availability), Claude Opus 5.5 accepts `role: "system"` messages immediately after a user turn in the `messages` array (subject to [placement rules](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages#limitations)). This feature is not available on Claude Sonnet 5. If you maintain code paths that rebuild the full message history to update instructions, switch them to system messages. After a rebuild, a request can get a 400 error, and [prompt cache](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) hits are lost.
17901805
179118062. **Lower prompt caching minimum:** The minimum cacheable prompt length on Claude Opus 5.5 is 512 tokens, down from 1,024 tokens on Claude Sonnet 5. Prompts that were too short to cache on Claude Sonnet 5 can create cache entries, with no code changes required. See [Prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching#cache-limitations) for per-model minimums.
17921807
models/opus-5-5/whats-new-opus-5-5 Changed · +9 / -5 lines
from line 62
6262| From Claude Opus 5.5, to Claude Fable 5.1 or Claude Mythos 5.1 | Yes, on the Claude API only |
6363| From Claude Opus 5.5, to any other model | No |
6464
65When a request carries a block the target model can’t read, the API drops it before the model sees it. The request succeeds, and dropped blocks aren’t billed. With the `thinking-binding-controls-2026-08-01` beta header, the drop is reported in a top-level `input_transformations` array. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). For switches that don’t involve Claude Opus 5.5, see [Which model switches keep the reasoning on the Claude API](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#which-model-switches-keep-reasoning).
65When a request carries a block the target model can’t read, the API drops it before the model receives it. The request succeeds, and dropped blocks aren’t billed. With the `thinking-binding-controls-2026-08-01` beta header, the API reports the drop in a top-level `input_transformations` array. See [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). For switches that don’t involve Claude Opus 5.5, see [Which model switches keep the reasoning on the Claude API](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#which-model-switches-keep-reasoning).
6666
67The API also checks whether anything before a Claude Opus 5.5 thinking block (the `system` prompt, the `tools`, or an earlier message) has changed since the block was produced. Keep the conversation append-only: change instructions or tools with [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) rather than edits.
67The API also checks whether anything before a Claude Opus 5.5 thinking block has changed since the model produced the block. This prefix check covers the `system` prompt, the `tools`, and every earlier message. Keep the conversation append-only: change instructions or tools with [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) rather than edits.
6868
69A request that replays a block after such a change, with `thinking.block_binding.prefix_mismatch_behavior` unset, gets a 400 error. This applies to accounts created on or after August 31, 2026, 00:00 UTC. [Preserved thinking availability](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#feature-availability) lists the platforms where this applies. On accounts created before that date, the request might or might not get the error. To drop the affected blocks instead, send the `thinking-binding-controls-2026-08-01` beta header and set the field to `"drop_block"`. See [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) and the migration guide’s [note on thinking blocks](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#thinking-blocks).
69Failing the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check) might or might not result in a [400 error](https://platform.claude.com/docs/en/api/errors#thinking-block-conversation-mismatch). To identify and handle both cases, see [Prefix checks on thinking blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks).
7070
71The prefix check runs on the Claude API and on [some cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#feature-availability).
72
73See [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) and the migration guide’s [note on thinking blocks](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#thinking-blocks).
74
7175### Some computer use tool versions are not supported
7276
7377Claude Opus 5.5 supports [computer use](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool) through the `computer_toolset_20260801` toolset. On Amazon Bedrock, Claude Opus 5.5 also accepts the `computer_20251124` tool with the `computer-use-2025-11-24` beta header. Claude Opus 5.5 returns a 400 error for any computer use tool version it doesn’t accept, such as `computer_20251124` on the Claude API. The Claude API’s `invalid_request_error` message names the rejected type and, after `Did you mean one of`, lists the tool types the model accepts. The message begins:
from line 84
8084
8185## Feature support
8286
83Claude Opus 5.5 supports [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message) (in beta), [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages), [task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets), [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) with a 512-token minimum cacheable prompt, [batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing), the [Files API](https://platform.claude.com/docs/en/build-with-claude/files), [PDF support](https://platform.claude.com/docs/en/build-with-claude/pdf-support), [vision](https://platform.claude.com/docs/en/build-with-claude/vision), and server-side and client-side tools (see [Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)). See each feature’s page for model availability.
87Claude Opus 5.5 supports [per-message effort](https://platform.claude.com/docs/en/build-with-claude/effort-per-message), [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages), [task budgets](https://platform.claude.com/docs/en/build-with-claude/task-budgets), [prompt caching](https://platform.claude.com/docs/en/build-with-claude/prompt-caching) with a 512-token minimum cacheable prompt, [batch processing](https://platform.claude.com/docs/en/build-with-claude/batch-processing), the [Files API](https://platform.claude.com/docs/en/build-with-claude/files), [PDF support](https://platform.claude.com/docs/en/build-with-claude/pdf-support), [vision](https://platform.claude.com/docs/en/build-with-claude/vision), and server-side and client-side tools (see [Tool use with Claude](https://platform.claude.com/docs/en/agents-and-tools/tool-use/overview)). Task budgets and per-message effort are in beta. See each feature’s page for model availability.
8488
8589### Fast mode
8690
from line 104
100104
101105* **The default effort is `medium`.** A request that omits `effort` runs at `medium`; on Claude Opus 5 it ran at `high`. Set `effort` explicitly and re-run your sweep; see [Calibrate effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#calibrate-effort).
102106* **More thinking per turn at a given effort level.** At the same [effort](https://platform.claude.com/docs/en/build-with-claude/effort) setting the model tends to think more per turn than Claude Opus 5, most of all at `xhigh` and `max`. Re-run your effort sweep rather than carrying a setting over, and leave room in `max_tokens` for the thinking. See [Calibrate effort](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#calibrate-effort).
103* **Text between tool calls comes back in thinking blocks.** The short notes the model writes between tool calls arrive as [progress-update `thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) rather than `text` blocks, so at the default `display: "omitted"` an application that streams them to its users goes quiet between tool calls, with no error. The migration guide explains [how to receive text between tool calls](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#text-between-tool-calls), and [User-facing progress updates](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates) covers how to ask for more of them.
107* **Text between tool calls comes back in thinking blocks.** The short notes the model writes between tool calls arrive as [progress-update `thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates) rather than `text` blocks. At the default `display: "omitted"`, an application that streams them to its users goes quiet between tool calls, with no error. The migration guide explains [how to receive text between tool calls](https://platform.claude.com/docs/en/models/opus-5-5/migration-guide#text-between-tool-calls). For how to ask for more of them, see [User-facing progress updates](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#user-facing-progress-updates).
104108* **More safeguard categories.** The model runs a biology safety classifier in addition to the cybersecurity one. As on Claude Opus 5, requests that push it to reproduce its internal reasoning in the response text might be declined with the `reasoning_extraction` category. See [Refusals and fallback in Claude Opus 5.5](https://platform.claude.com/docs/en/models/opus-5-5/whats-new-opus-5-5#refusals-and-fallback) and [Safeguard refusals](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#safeguard-refusals).
105109* **Sharper reading of charts, diagrams, and screenshots.** The model reads values off dense charts and layout-dependent visuals much more precisely without tools, so prompt-side vision workarounds built for earlier models might no longer be needed; image tools still add accuracy on the densest inputs. See [Tools for complex visual inputs](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-opus-5-5#tools-for-complex-visual-inputs).
106110
models/sonnet-5-5/migration-guide Changed · +14 / -6 lines
from line 838
838838
839839### Thinking blocks are tied to the model and the conversation
840840
841Claude Sonnet 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and earlier models, and, on the Claude API and Claude Models on Google Cloud (Google managed), from Claude Haiku 5.5. It doesn’t read blocks from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model. The API drops blocks the model can’t read. The request still returns 200, and dropped blocks aren’t billed. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
841Claude Sonnet 5.5 reads thinking blocks from Claude Sonnet 5, Claude Opus 4.8, Claude Haiku 4.5, and [earlier models](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#earlier-models). On the Claude API and Claude Models on Google Cloud (Google managed), it also reads them from Claude Haiku 5.5. It doesn’t read blocks from Claude Opus 5, Claude Opus 5.5, or any Claude Fable or Claude Mythos model.
842842
843Each Claude Sonnet 5.5 thinking block is also signed over the conversation before it. Keep conversations append-only, and change instructions or tools with [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages). A request can replay a block after an edit to earlier history and leave `thinking.block_binding.prefix_mismatch_behavior` unset. On accounts created on or after August 31, 2026, 00:00 UTC, that request gets a 400 error. [Preserved thinking availability](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#feature-availability) lists the platforms where this applies. Thinking blocks that Claude Sonnet 5.5 produces work only in the account that produced them or in an account linked to it. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
843The API drops blocks the model can’t read. The request returns 200, and dropped blocks aren’t billed. See [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models).
844844
845Keep conversations append-only, so that thinking blocks pass the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check). To change instructions or tools, see [Mid-conversation system messages and tool changes](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages).
846
847Failing the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check) might or might not result in a [400 error](https://platform.claude.com/docs/en/api/errors#thinking-block-conversation-mismatch). To identify and handle both cases, see [Prefix checks on thinking blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks).
848
849The prefix check runs on the Claude API and on [some cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#feature-availability).
850
851Claude Sonnet 5.5 thinking blocks work only in the account that produced them or in an account linked to it. See [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
852
845853### Some computer use tool versions are not supported
846854
847855Claude Sonnet 5.5 supports computer use through the `computer_toolset_20260801` toolset. On Amazon Bedrock, Claude Sonnet 5.5 also accepts the `computer_20251124` tool with the `computer-use-2025-11-24` beta header. Claude Sonnet 5.5 returns a 400 error for any computer use tool version it doesn’t accept, such as `computer_20251124` on the Claude API. It doesn’t accept `computer_20250124` on any platform.
848856
849Integrations that use the toolset need no change. To move to the toolset, replace `computer_20251124` or `computer_20250124` with `computer_toolset_20260801`, and drop that version’s beta header. [Migrate from `computer_20251124`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124) lists the request and agent-loop changes.
857Integrations that use the toolset need no change. To move to the toolset, replace `computer_20251124` or `computer_20250124` with `computer_toolset_20260801`, and drop that version’s beta header. For the request and agent-loop changes, see [Migrate from `computer_20251124`](https://platform.claude.com/docs/en/agents-and-tools/tool-use/computer-use-tool#migrate-from-computer-20251124).
850858
851859If you send the `fine-grained-tool-streaming-2025-05-14` beta header, remove it when you move to the toolset. Alongside a toolset entry, it returns a 400 error. Set `eager_input_streaming: true` on each tool that needs it instead.
852860
from line 1195
11871195### Other changes
11881196
11891197* **About 30 percent more tokens:** Claude Sonnet 5.5 uses Claude Sonnet 5’s tokenizer. Against Claude Sonnet 4.6, Claude Sonnet 4.5, and Claude Haiku 4.5, the same text produces about 30 percent more tokens, depending on the content. Recount with [token counting](https://platform.claude.com/docs/en/build-with-claude/token-counting), and revisit `max_tokens` and cost.
1190* **Effort:** `xhigh` is new, and the levels are recalibrated. See [Recommended changes](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#recommended-changes).
1198* **Effort:** Claude Sonnet 5.5 supports `xhigh`, and the levels are recalibrated. See [Recommended changes](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#recommended-changes).
11911199* **Images:** Claude Sonnet 5.5 uses the high-resolution image tier, up to 2,576 pixels on the long edge and up to 4,784 visual tokens for an image. Claude Sonnet 4.6, Claude Sonnet 4.5, and Claude Haiku 4.5 stop at 1,568 pixels and 1,568 tokens. A 2000×1500 image costs about 2.5 times as many tokens on Claude Sonnet 5.5. See [Resolution and token cost](https://platform.claude.com/docs/en/build-with-claude/vision#evaluate-image-size).
11921200
11931201### Migrating from Claude Sonnet 4.5 or earlier
from line 1220
12121220
12131221**Computer use.** Claude Sonnet 5.5 doesn’t accept `computer_20250124`. See [Some computer use tool versions are not supported](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#computer-use-toolset).
12141222
1215**Effort.** Claude Sonnet 4.5 has no effort parameter. Set an effort level explicitly, as [Recommended changes](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#recommended-changes) describes.
1223**Effort.** Claude Sonnet 4.5 has no effort parameter. Set an effort level explicitly (see [Recommended changes](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#recommended-changes)).
12161224
12171225**Context and output.** Claude Sonnet 5.5 has a larger context window and a higher output limit. See the [Claude Sonnet 5.5](https://platform.claude.com/docs/en/models/sonnet-5-5/overview) model page. Remove any context-window beta header.
12181226
models/sonnet-5-5/whats-new-sonnet-5-5 Changed · +11 / -9 lines
from line 58
5858| From Claude Sonnet 5.5, to Claude Opus 5.5, Claude Fable 5.2, or Claude Mythos 5.2 | Yes, on the Claude API and Claude Models on Google Cloud (Google managed) only |
5959| From Claude Sonnet 5.5, to any other model | No |
6060
61When a request carries a block the target model can’t read, the API drops it before the model sees it. The request succeeds, and dropped blocks aren’t billed. With the `thinking-binding-controls-2026-08-01` beta header, the drop is reported in a top-level `input_transformations` array. See [Switching models mid-conversation](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). For switches that don’t involve Claude Sonnet 5.5, see [Which model switches keep the reasoning on the Claude API](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#which-model-switches-keep-reasoning).
61When a request carries a block the target model can’t read, the API drops it before the model receives it. The request succeeds, and dropped blocks aren’t billed. With the `thinking-binding-controls-2026-08-01` beta header, the API reports the drop in a top-level `input_transformations` array. See [Switch models and back](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#switching-models). For switches that don’t involve Claude Sonnet 5.5, see [Which model switches keep the reasoning on the Claude API](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#which-model-switches-keep-reasoning).
6262
63The API also checks whether anything before a Claude Sonnet 5.5 thinking block has changed since the block was produced: the `system` prompt, the `tools`, or an earlier message. Keep the conversation append-only: change instructions or tools with [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) rather than edits.
63The API also checks whether anything before a Claude Sonnet 5.5 thinking block has changed since the model produced the block. This prefix check covers the `system` prompt, the `tools`, and every earlier message. Keep the conversation append-only: change instructions or tools with [mid-conversation system messages](https://platform.claude.com/docs/en/build-with-claude/mid-conversation-system-messages) rather than edits.
6464
65A request that replays a block after such a change, with `thinking.block_binding.prefix_mismatch_behavior` unset, gets a 400 error. This applies to accounts created on or after August 31, 2026, 00:00 UTC. [Preserved thinking availability](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#feature-availability) lists the platforms where this applies. On accounts created before that date, the request might or might not get the error. To drop the affected blocks instead, send the `thinking-binding-controls-2026-08-01` beta header and set the field to `"drop_block"`.
65Failing the [prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks#prefix-check) might or might not result in a [400 error](https://platform.claude.com/docs/en/api/errors#thinking-block-conversation-mismatch). To identify and handle both cases, see [Prefix checks on thinking blocks](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/prefix-checks).
6666
67`block_binding` works only with `thinking: {"type": "adaptive"}`. With any other thinking setting, you can’t send `block_binding`. Instead, strip the block the error names and every later `thinking` and `redacted_thinking` block. Leave them out of later requests, and retry.
67The prefix check runs on the Claude API and on [some cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#feature-availability).
6868
6969See [Preserved thinking](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking) and the migration guide’s [note on thinking blocks](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#thinking-blocks).
7070
from line 116
116116
117117### Thinking blocks stay with the account that produced them
118118
119Thinking blocks that Claude Sonnet 5.5 produces work only in the account that produced them, or in an account linked to it. When another account sends one of these blocks, the API drops the block before the model receives it, and the request succeeds. On the Claude API and Claude Models on Google Cloud (Google managed), you can see which blocks were dropped. Send the `thinking-binding-controls-2026-08-01` beta header, and the response lists each dropped block in `input_transformations` with `reason: "organization_binding_mismatch"`. Blocks from earlier models aren’t affected. See [Thinking blocks stay with the account that produced them](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
119Thinking blocks that Claude Sonnet 5.5 produces work only in the account that produced them, or in an account linked to it. When another account sends one of these blocks, the API drops the block before the model receives it, and the request succeeds. Blocks from Claude Haiku 5.5, Claude Fable 5.2, and Claude Mythos 5.2 follow the same rule.
120120
121On the Claude API and Claude Models on Google Cloud (Google managed), you can see which blocks were dropped. Send the `thinking-binding-controls-2026-08-01` beta header, and the response lists each dropped block in `input_transformations` with `reason: "organization_binding_mismatch"`. See [Accounts and cloud platforms](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#account-bound-thinking).
122
121123## Behavior differences
122124
123Claude Sonnet 5.5 differs from Claude Sonnet 5 in several ways that show up without any code change. [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5) has guidance for each:
125For guidance on each of the following, see [Prompting Claude Sonnet 5.5](https://platform.claude.com/docs/en/build-with-claude/prompt-engineering/prompting-claude-sonnet-5-5). Claude Sonnet 5.5 differs from Claude Sonnet 5 in these ways, which show up without any code change:
124126
125127* **Effort levels are recalibrated.** An [effort](https://platform.claude.com/docs/en/build-with-claude/effort) level doesn’t produce the same amount of thinking as it did on Claude Sonnet 5. Re-run your effort sweep rather than carrying a setting over. Start at `high` unless your workload is agentic or latency-sensitive. For agentic coding and multistep tool use, start at `medium` for well-specified tasks and move to `high` for harder or longer ones. For chat and other latency-sensitive work, start at `medium` or `low`.
126128* **Text between tool calls comes back in thinking blocks.** Between tool calls, notes longer than a sentence or two come back as [progress-update `thinking` blocks](https://platform.claude.com/docs/en/build-with-claude/thinking#progress-updates). Shorter remarks stay `text`. At the default `display: "omitted"`, the progress-update blocks’ text is empty, so an application that streams those notes to its users goes quiet between tool calls, with no error. If you [turn off up-front thinking with `between_tools`](https://platform.claude.com/docs/en/models/sonnet-5-5/whats-new-sonnet-5-5#turn-off-up-front-thinking), the text comes back. To receive it, see [Text between tool calls is returned in thinking blocks](https://platform.claude.com/docs/en/models/sonnet-5-5/migration-guide#text-between-tool-calls) in the migration guide.
agents-and-tools/agent-skills/claude-api-skill Changed · +1 / -1 lines
from line 184
1841841. **Scope:** Checks whether your integration is affected, then sends three test requests to confirm that the API reports a deliberate edit.
1851852. **Find:** Captures a few of your own multi-turn sessions, diffs consecutive requests, and lists each place your code edits the prefix.
1861863. **Measure:** Replays the sessions with `"drop_block"` and reports which conversations lose `thinking` blocks, at which turn, and why.
1874. **Fix:** Replaces one edit at a time with the matching pattern in [Make changes without editing the prefix](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking#replace-prefix-edits), and measures again after each change.
1874. **Fix:** Replaces each edit with the matching pattern in [Change tools or instructions without failing the prefix check](https://platform.claude.com/docs/en/build-with-claude/preserved-thinking/change-tools-or-instructions), and measures again after each one.
1881885. **Report:** Summarizes each cause, the change made for it, and the counts before and after.
189189
190190If your project has an eval, the skill also compares scores and token usage with and without dropped `thinking` blocks.
manage-claude/compliance-security-posture/events-reference Changed · +2 / -2 lines
from line 57
5757 "organization_uuid": "91012d09-e48b-438e-a489-1bebfd8fa6f9",
5858 "actor": {
5959 "type": "user_actor",
60 "email_address": "[email protected]",
60 "email_address": "[email protected]",
6161 "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu",
6262 "ip_address": "192.0.2.34",
6363 "user_agent": "Mozilla/5.0..."
from line 72
7272
7373Do not read the absence of an activity as a sign that nothing changed. For current results, see [Security posture results reference](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/results-reference); its endpoint can omit a control that an activity names.
7474
75* Changes from before the [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed) began recording these activities for the organization, or while the Compliance API was off, never added later.
75* Changes from before the [Activity Feed](https://platform.claude.com/docs/en/manage-claude/compliance-activity-feed) began recording these activities for the organization, or while the Compliance API was off. The feed never adds activities for them later.
7676* Rarely, a change of any kind.
7777* Every end date that arrives: not all get an activity, so do not wait for one.
7878* Each time the Security posture page is turned off or on: do not rely on a [detection rule](https://platform.claude.com/docs/en/manage-claude/compliance-security-posture/detect-changes) to detect it.
manage-claude/compliance-security-posture/send-events Changed · +1 / -1 lines
from line 40
4040 "organization_uuid": "91012d09-e48b-438e-a489-1bebfd8fa6f9",
4141 "actor": {
4242 "type": "user_actor",
43 "email_address": "[email protected]",
43 "email_address": "[email protected]",
4444 "user_id": "user_01WxYzAbCdEfGhJkMnPqRsTu",
4545 "ip_address": "192.0.2.34",
4646 "user_agent": "Mozilla/5.0..."