How to Use Claude Opus 4.8 | 1M Context Default and API Design Changes

What Is Claude Opus 4.8 — What Changes with the 1M Context Default and 128k Max Output

According to the Anthropic official Claude Opus 4.8 announcement and the whats-new-claude-4-8 documentation, Claude Opus 4.8 now defaults to a 1M token context window on three platforms: Claude API, Amazon Bedrock, and Vertex AI. Microsoft Foundry remains at 200k by default and requires explicit configuration to use 1M. Max output is 128k tokens, and the minimum cacheable length for prompt cache has dropped to 1,024 tokens compared to before, enabling cache utilization for finer-grained diffs.

Thanks to improved adaptive thinking, the model now fires thinking tokens only on turns that require them, even with the same effort setting. Previously, effort=high would consistently trigger extended thinking; in Opus 4.8, thinking volume adjusts dynamically based on the complexity of the input task. High-resolution image input has also been added, supporting images up to 2,576px on the long side. Task budgets, the advisor tool, and computer use are also included in the supported feature set. Note that sending non-default values for temperature, top_p, or top_k will return a 400 error — the same behavior as Opus 4.7 — so any implementations that modify sampling parameters should take care. Long-context pricing may apply beyond the 1M context threshold, so be sure to check the platform release notes for billing conditions before going to production.

Impact of the 1M Context Default on Long-Context Agents

For designers of long-context agents (code analysis, long-form summarization, cross-document RAG), the 1M context default is a change that prompts a rethinking of chunking strategies. Designs that previously assumed "compress into 200k context via chunking, summarization, and RAG re-ranking" can now be replaced by designs that "stream directly into 1M for batch processing" — a shift that simplifies both accuracy and implementation in many scenarios.

However, long-context pricing per token is higher in certain ranges, so always recalculate cost estimates based on actual anticipated usage. Combining this with a strategy of applying prompt cache at 1,024-token granularity lets you reduce the base cost of long contexts while lowering the per-query cost for repeated requests. In practice, the two-tier approach of "1M for long context, fine-grained caching for repetition" is the pragmatic solution.

Mid-Conversation System Messages — A New Pattern for Swapping Instructions in Long Sessions

According to the mid-conversation system messages documentation, Opus 4.8 now allows inserting role: "system" after user turns in the messages array. There are placement rules: system turns cannot be placed immediately after an assistant turn and must be inserted after a user turn. The system prompt at the beginning of messages remains in effect, and the additional entries act as instruction updates mid-conversation.

{
  "model": "claude-opus-4-8",
  "system": "You are a polite assistant",
  "messages": [
    {"role": "user",      "content": "Start the research phase"},
    {"role": "assistant", "content": "(research results)"},
    {"role": "user",      "content": "Now move to the implementation phase"},
    {"role": "system",    "content": "From here, code blocks are required and explanations should be minimal"}
  ]
}

The biggest benefit is the ability to switch instructions while maintaining prompt cache hits. Previously, changing the system prompt mid-session would invalidate the cache from the beginning, so designs for long sessions were effectively forced to "keep the same system prompt throughout." With Opus 4.8, only the section after an inserted mid-conversation system message is subject to cache invalidation — the initial system prompt and initial user turns remain cached.

Design Patterns — Phased Application and Tone Guide Updates

As a concrete usage pattern, the first is swapping task-specific instructions between stages of a multi-step workflow. For example, in a long session progressing through "research → design → implementation → review," inserting a task instruction at the start of each phase — such as "Now entering the implementation phase. Code blocks required, minimize natural language explanations" — yields output optimized for each phase.

The second is phased application of tone guides: start the conversation with an exploratory, casual tone, then switch to "from here on, use bullet points and numbers for conciseness" when moving into the conclusion stage. The third is dynamic reinforcement of safety constraints: when the conversation enters sensitive territory, you can override constraints with "from here on, always recommend consulting a professional for medical or legal topics." All of these previously required a single monolithic system prompt, and this change raises the degree of design flexibility considerably.

stop_details Refusal Design — Routing cyber / bio / null as Separate Branches

In the refusal categories section of handling-stop-reasons, the stop_details.category field has been officially documented. The values are cyber, bio, or null, and a human-readable explanation field is also returned. Implementations that previously branched only on stop_reason: "refusal" can now route with category-level granularity.

resp = client.messages.create(model="claude-opus-4-8", messages=msgs)
if resp.stop_reason == "refusal":
    cat = resp.stop_details.category   # "cyber" / "bio" / null
    if cat == "cyber":
        route_to_security_review(resp.stop_details.explanation)
    elif cat == "bio":
        route_to_expert_review(resp.stop_details.explanation)
    else:                              # null = other, generic fallback
        route_to_generic_fallback(resp.stop_details.explanation)

As a design pattern, routing cyber refusals to a security review flow — where a separate engine (a model with stricter policy guards) re-evaluates the request — is one example. Bio refusals are best sent to an expert review flow, passing them to human reviewers in the medical or life sciences domain. Null (other) refusals can follow a generic fallback pattern, returning a general refusal message with a support contact link as the standard solution.

Migrating Existing Implementations — Moving Away from Single-Branch Refusal Handling

Implementations currently branching only on stop_reason: "refusal" can migrate by reading stop_details.category and expanding the branch targets. Falling back to the existing behavior for null and adding dedicated flows only for cyber/bio allows for incremental adoption while minimizing risk. Surfacing the explanation field in logs and monitoring dashboards also makes refusal cause analysis significantly easier in production.

Claude Opus 4.7 → 4.8 Migration Steps — Opus 4.6 Fast Mode Deprecation and Adaptive Thinking Improvements

The implementation-side migration is complete in three steps:

1. Switch the model ID to claude-opus-4-8 — With the context window default now at 1M, review any processes that were explicitly pinning context window to 200k on the request side. Systems using Microsoft Foundry remain at 200k by default, so organize your per-platform branching accordingly.
2. Review your effort settings — Adaptive thinking improvements have changed how thinking token consumption behaves. If you were running heavy processing at effort=high, Opus 4.8 may deliver equivalent quality at effort=medium, presenting a cost reduction opportunity. It is safest to benchmark representative requests before applying changes to production.
3. Migrate Opus 4.6 fast mode usage — Opus 4.6 fast mode is now marked as deprecated, and the Anthropic announcement indicates it will be retired approximately 30 days out. Choose either Opus 4.7 or Opus 4.8 fast mode (research preview) as your migration target.

Additionally, the CLAUDE_CODE_OPUS_4_6_FAST_MODE_OVERRIDE environment variable was originally announced for removal on 2026-06-01. As of this article's update (2026-06-06), that date has passed, and fast mode switching in Claude Code is now consolidated under the /fast toggle (available for Opus 4.6 / 4.7 / 4.8). Any build scripts that depend on this environment variable should be treated as already removed — assume it is a no-op — and migrate to /fast-based operation. For the exact removal timeline, check the latest platform release notes.

Taking Advantage of the Lower Minimum Cacheable Length for Prompt Cache

The drop in the minimum cacheable length for prompt cache to 1,024 tokens is subtle but impactful. The previous constraint that "a substantial length was needed to cache" has been relaxed, making it viable to design for cache hits on smaller units such as mid-conversation diff prompts and dynamically assembled tool definitions.

Combined with mid-conversation system messages, it is now practical to design long sessions that maintain cache efficiency while updating instructions. Writing a single operational rule on the agent side — "update instructions without breaking the cache" — can produce a visible reduction in cumulative costs for long sessions.

Claude Code v2.1.154 Synchronized Release — Opus 4.8 Default and Dynamic Workflows Changes

According to the Claude Code v2.1.154 release notes, the default model for new sessions has switched to Opus 4.8. For Max plan users, Opus 4.8 fast mode is the default, and /effort xhigh is also enabled by default. The default quality for complex tasks has been raised, meaning output quality when /effort is not explicitly specified has improved by one level.

The biggest new feature is Dynamic Workflows (/workflows), which allows you to define and execute multi-step agent plans. The flow is to declare steps with /workflow new and execute them with /workflows run <name>, consolidating what previously required piping multiple claude -p calls manually. The Lean system prompt is now the default, reducing the fixed overhead at the start of prompts. Ecosystem improvements have also advanced simultaneously, including defaultEnabled: false declarations for plugins and pinning in the /plugin Discover tab.

Breaking Changes That Scripts Need to Follow

For those writing internal scripts, the critical item to watch is the re-changed behavior of /simplify. /simplify, which had been changed to a wrapper for another command in v2.1.152, has been changed back to its own distinct behavior in v2.1.154. If you call /simplify in any scripts, be sure to verify that it behaves as expected.

The renaming of the /effort slider labels to "Faster/Smarter" affects only the user experience and has no impact on API compatibility. Safety fixes include a block correction for rm -rf $HOME with a trailing slash and a $TMPDIR consistency fix, raising the robustness of automatic dangerous command rejection by one level.

Sources

• Claude Opus 4.8 Announcement (Anthropic)
• Opus 4.8 Feature Diff (whats-new-claude-4-8)
• Mid-conversation system messages specification
• stop_details specification (handling-stop-reasons#refusal-categories)
• Platform release notes
• Claude Code v2.1.154 Release Notes (GitHub)