Skip to main content
reopt Handbook
reopt Handbook
Claude Code Complete Guide

Setup

Plan and Environment SetupMastering CLAUDE.md

Multi-session & Agents

Multi-session WorkflowSubagents

Automation & Extension

HooksMCP IntegrationSkills and Slash Commands

Workflow

Plan ModeContext ManagementIDE IntegrationHeadless and CI/CD

Practice

Vibe Coding PatternsPrompting Best Practices

Verification

Verification ReportUpdate Log
Handbook›Claude Code Complete Guide›Update Log
한국어KOEnglishEN

Update Log

English edition changes for the Claude Code Complete Guide.

Written and reviewed by Eric Han · Co-founder & CTO, reopt

2026-10-23 · Claude Code 2.1.308

Compared v2.1.299–v2.1.308 in the official changelog with Commands and the CLI reference. npm latest, next, and stable all resolve to 2.1.308. The fetched changelog has no entries for v2.1.297 or 298, so their changes are not inferred.

  • Permission defaults (v2.1.302): without an explicit mode, claude -p and Agent SDK sessions on third-party providers, with telemetry disabled, or on fresh installs start in default. This supersedes the v2.1.285 auto-default guidance; --permission-mode auto remains an explicit option.

  • Skills and hooks (v2.1.299–304): UserPromptSubmit runs before skill or custom-command expansion; blocking it also prevents embedded shell execution. A skill's own hook starts with the following prompt. Tool validation checks updatedInput from PreToolUse and PermissionRequest. At most 12 prompt/agent hooks of an event run concurrently; skill hooks from one source are limited to 1,024 hooks and 16,384 matcher characters per session.

  • Subagents (v2.1.302): fork subagents are on by default in -p, the SDK, Desktop, and VS Code (CLAUDE_CODE_FORK_SUBAGENT=0 disables them; claude mcp serve excludes them). Main-conversation subagents run in the background, while their own Agent calls default to foreground in those environments.

  • Context (v2.1.299, 302, 304): idle compaction compresses a 200K+ token conversation after roughly 54 idle minutes. /config exposes its toggle; idleCompaction: false disables it and CLAUDE_CODE_IDLE_COMPACT_MIN_TOKENS sets the threshold. The changelog states v2.1.290+ for both settings. Compaction resends the skill list; /reload-skills sends only new or changed skills.

  • API and Design: /claude-api managed-agents-secure (v2.1.304) compares configuration against the security guide without modifying it; api-version (v2.1.307) helps migrate to API version 2026-10-21. The reference adds /design consent and /design revoke; the user must enter consent themselves. Standalone claude.ai/design, used by /design-login and /design-sync, closes by 2026-12-14.

  • MCP and policy (v2.1.299–307): an mcp__a allow rule no longer reaches server a__b; use mcp__<server>__* with its complete normalized name. From v2.1.305, managed-mcp.json stdio servers using ${VAR} only in env are not filtered by allowedMcpServers; block them explicitly with deniedMcpServers. v2.1.307 limits HTTP MCP retries after disconnects to read-only or idempotent tools.

  • Operations and diagnostics: claude remote-control --sandbox and --no-sandbox fail from v2.1.300; use sandbox.enabled. Runner checkout hooks default to 30 minutes in v2.1.307 (--checkout-hook-timeout-min, 0 disables the limit). The claude_code.safety_event OTel event records blocked or prompted tool calls. v2.1.308 announces only general fixes and reliability improvements.

  • Security and recovery: reviewed fixes for hook-approved writes in plan mode, sandbox symlink boundaries, third-party gateway credential forwarding, duplicate tool execution (v2.1.299), and worktree removal confirmation (v2.1.301, 304). sandbox.allowNestedUserNamespaces (v2.1.305) can bypass filesystem protections; review isolation before enabling it for Chromium or rootless podman on Linux.

  • Code Review and mods: @claude review stop (off or pause) ends a PR’s always-review subscription without starting another review (v2.1.307). v2.1.304 adds e.isReadOnly and decider: "person" to mod tool.check; the latter requires a permission dialog or host callback and denies with the mod reason when neither is available.

Sources: Changelog, Commands, CLI reference, Hooks, Subagents, npm dist-tags.

October 10, 2026 release refresh

Updated for Claude Code v2.1.293–v2.1.296 (October 7–9) and the Claude Haiku 5.5 model docs. npm checked on October 10, 2026 KST: latest/next=2.1.296, stable=2.1.287.

  • Haiku 5.5 (released 2026-10-07): claude-haiku-5-5 is the default Haiku on the Anthropic API from v2.1.293. setup, context, and prompting now cover its 1M context window, 128K output, pricing split at 100,000 prompt tokens ($0.10/$0.50, then $0.50/$2.50), medium default effort in Claude Code, and always-on thinking.
  • Sonnet 5.5 cache reads: Sonnet 5.5 prompt cache reads cost $0.10/MTok. From v2.1.296, /cost, the status line, --max-budget-usd, and the SDK's cost figures use that price too (was $0.20). The Korean edition corrects the figure in setup.
  • Hooks: added onFailure: "block" for command and HTTP hooks (v2.1.295) and the improved judging of Stop and SubagentStop prompt hooks (v2.1.294).
  • Subagents: added the 32-skill preload cap on skills (v2.1.295), the autoCompactWindow frontmatter field (v2.1.296), and agentType in the subagentStatusLine payload (v2.1.293).
  • MCP and headless: mcp adds the MCP description limits (4,096 characters up front, 16,384 through tool search) and the 16 MiB WebSocket message limit; headless adds the retry variables CLAUDE_CODE_RETRY_WATCHDOG_MAX_WAIT_MS (v2.1.295) and CLAUDE_CODE_OVERLOADED_RETRY_MAX_DELAY_MS (v2.1.296).

Sources: official changelog, Model configuration, Hooks, Subagents, MCP, CLI reference, Claude Haiku 5.5 overview, Pricing, npm dist-tags.

Updated: index, setup, context, prompting, hooks, subagents, mcp, headless, and verification in English; the Korean edition updates vibe-coding instead of prompting.

October 7, 2026 release refresh (previous)

Updated for Claude Code v2.1.284–v2.1.292 (September 28–October 6) and the Claude Sonnet 5.5 model docs. npm checked on October 7, 2026 KST: latest/next=2.1.292, stable=2.1.285.

  • Sonnet 5.5 (released 2026-09-28): claude-sonnet-5-5 is the default Sonnet on the Anthropic API from v2.1.284, with a 1M context window, 128K output, $2/$10 per MTok (cache reads $0.20), a medium default effort in Claude Code, and classifier fallback of cybersecurity flags to Sonnet 5 (biology flags are refused).
  • Permission defaults: auto mode as the starting mode now covers interactive terminal and VS Code sessions on every plan and provider (v2.1.284) and claude -p and Python Agent SDK sessions on third-party providers or with telemetry off (v2.1.285); headless notes it next to the advice to pass a permission mode explicitly in CI.
  • Ultracode and effort: noted in setup and prompting that Ultracode is a toggle separate from the effort level (v2.1.284).
  • Headless: added the narrower --bare scope and the unified retry limit (v2.1.286), and recorded that the CLI reference now agrees that --system-prompt can be combined with its -file form.
  • Operations: managed allowedProviders and sandbox setting protection (v2.1.285), Claude Mods (v2.1.287), default stdio MCP protocol negotiation (v2.1.292), and the claude purge rename (v2.1.288).

Sources: official changelog, Model configuration, Permission modes, MCP, Claude Sonnet 5.5 overview, npm dist-tags.

Updated: index, setup, prompting, headless, and verification in English; the Korean edition also updates context and vibe-coding.

September 26, 2026 release refresh (previous)

Updated for Claude Code v2.1.280–v2.1.283 (September 22–25) and the Claude Opus 5.5 model docs. npm checked on September 26, 2026 KST: latest/next=2.1.283, stable=2.1.274.

  • Opus 5.5 (released 2026-09-22): claude-opus-5-5 is the default Opus and fast-mode model from v2.1.280 and the default model on most plans (now including Pro and Team Standard) and on the Anthropic API, Claude Platform on AWS, Bedrock, and Google Cloud Agent Platform. Documented 1M context, 128K output, $4/$20 per MTok with $0.20 cache reads, always-on adaptive thinking, default effort medium, fast mode at $8/$40, and classifier fallback (biology to Opus 5, cybersecurity to Opus 4.8).
  • Effort: noted that a top-level user effortLevel does not apply to Opus 5.5 and how to save a per-model level (setup, prompting).
  • Messages API differences: forced tool_choice, disabled/fixed-budget thinking, model- and conversation-bound thinking blocks, and computer_20251124 rejection on the Claude API and Google Cloud.
  • Holding back releases: v2.1.283 managed deniedModels and availableModelsMatch: "exact", paired with requiredMinimumVersion.
  • Operations: auto mode as the start mode on third-party providers or with telemetry off (v2.1.283), server-side auto-mode classifier default and ignored project/local OTel variables (v2.1.282), the two-minute dangerous-rm timeout, "attribution": false, AGENTS.md on more providers, and --agents file paths (v2.1.281), plus /doctor prompt-audit and combined --system-prompt forms (v2.1.283).

Sources: official changelog, Model configuration, Fast mode, Claude Opus 5.5 overview, What's new in Claude Opus 5.5, npm dist-tags.

Updated: index, setup, context, subagents, prompting, and verification in English; the Korean edition also updates vibe-coding and headless.

September 12, 2026 release refresh (previous)

Updated for Claude Code v2.1.263–v2.1.269 (September 6–11). npm checked on September 12, 2026 KST: latest/next=2.1.269, stable=2.1.236. Keep latest-feature evaluation separate from a team's stable-channel rollout.

  • Plugins: claude plugin eval produces JSON and HTML evaluation reports; install, uninstall, update, enable, and disable accept --json. --plugin-dir can point to a parent directory containing multiple plugins.
  • Commands and settings: /output-style [name] works over Remote Control and in cloud/headless sessions. maxEffortLevel caps effort globally or per model under modelSettings. bashEditDiffEnabled adds file-edit diffs to Bash results.
  • Recovery and compatibility: 2.1.266 fixes forced gateway sign-in; 2.1.268 fixes HTTP 400s on Anthropic-compatible endpoints introduced in 2.1.265. /goal retries with backoff or pauses with a reason after API, network, or usage-limit failures.
  • Permissions and operations: fixes cover symlink deny/ask rules, Bash tee write boundaries, and secrets in MCP/plugin errors. WebFetch has a default 300-second deadline. /ultrareview --post posts the PR comment directly when findings arrive.

Sources: official changelog, npm dist-tags.

Updated: both locales of the index, setup, verification, and relevant command/operations chapters. Entries below retain their historical verification dates.

2026-09-05

  • Raised the baseline to Claude Code v2.1.261 and npm latest/next=2.1.261, stable=2.1.236 after reviewing v2.1.252~261 and the Claude Fable 5.1 docs.
  • Documented Claude Fable 5.1 (claude-fable-5-1, released 2026-09-01) as the default Fable model from v2.1.257 with a v2.1.255 minimum: alias resolution, /model claude-fable-5 for the legacy model, gateway sessions staying on Fable 5, pricing with $0.25/MTok cache reads, retention, and the Mythos 5.1 distinction.
  • Added the category-based classifier fallback table, switchModelsOnFlag, and the third-party ANTHROPIC_DEFAULT_OPUS_MODEL requirement.
  • Added Fable 5.1 Messages API breaking changes (forced tool_choice, model-bound thinking blocks, history-editing invalidation from 2026-08-31 accounts) and additive features (per-message effort, turn-scoped system messages, display: "updates", provenance).
  • Updated effort guidance (no default-effort hold on Opus 5 and Fable 5.1, session-only s, cache-preserving effort changes on Fable 5.1), 1M auto-compact timing, CLAUDE_CODE_SUBAGENT_MODEL_FORCE, and the [1m] subagent fix across index, setup, context, subagents, headless, and verification.

2026-08-28

  • Raised the baseline to Claude Code v2.1.247 and npm latest/next=2.1.247, stable=2.1.231 after reviewing v2.1.239~247.
  • Added loop usage breakdowns, managed model picker/pricing and prompt-cache TTL settings, and the Auto-mode rules tab.
  • Added partial subagent continuation, fallback-model handling, resilient headless auto-continuation, /claude-api upgrade/cost optimization, and feedback drafts.
  • Added the Sonnet 5 1M compaction threshold change plus wildcard, marketplace, and third-party gateway credential hardening.

2026-08-20

  • Raised the baseline to Claude Code v2.1.237 and npm latest/next=2.1.237, stable=2.1.228 after reviewing v2.1.221~237.
  • Added interactive fork mode, background subagent spawning, cross-session messaging and session mentions, and removal of the old 200-per-session total.
  • Added self-hosted runners, remote-control --continue, GitLab merge-request workflows, plugin command/archive sources, and server-supplied runner hooks.
  • Added ANTHROPIC_DEFAULT_MODEL, the newer-model Task/Todo default and compatibility flag, the Concise output style, prompt-caching fix, and the release window's trust, sandbox, OAuth, worktree, and Remote Control hardening.

2026-08-03

  • Re-checked the official changelog, local CLI, and npm: v2.1.220 remains latest and next, while v2.1.212 remains stable.
  • Found no stable release or command addition, removal, or rename after the August 1 update.
  • Updated the cover and verification dates while retaining the v2.1.206–220 operating guidance.

2026-08-01

  • Raised the baseline to Claude Code v2.1.220 and checked npm dist-tags (latest=2.1.220, stable=2.1.212, next=2.1.220).
  • Updated model guidance for Opus 5 as the default Opus path, its 1M context and fast-mode support, current provider alias resolution, and full-name pinning.
  • Documented the /fork background-session and /subtask inherited-context split, 200-per-session and 20-concurrent subagent defaults, configurable three-layer nesting, and budget enforcement for background subagents.
  • Added sandbox.network.strictAllowlist, sandbox.filesystem.disabled, DirectoryAdded, mcp_server_errors, nested --forward-subagent-text, medium workflow sizing, background /code-review, and manual-only /verify and /code-review behavior.

2026-07-10

  • Updated the English handbook baseline to Claude Code v2.1.205 after checking the official changelog and npm dist-tags (latest=2.1.205, stable=2.1.197; excluded next=2.1.206 because it has no public changelog entry yet).
  • Added v2.1.202 workflow sizing and OTel attributes, and clarified that /review is the fast single-pass path while /code-review <level> <PR> is the multi-agent path.
  • Added v2.1.203 Agent View, background session, worktree, Remote Control, login-expiry, and MCP roots operating notes.
  • Added the v2.1.204 headless SessionStart hook-streaming fix and v2.1.205 Auto-mode transcript protection, unresolved rm -rf prompting, --json-schema validation fixes, full /doctor setup checkup with /checkup alias, and updater/Agent View improvements.

2026-07-04

  • Updated the English handbook baseline to Claude Code v2.1.201 after checking the official changelog and npm dist-tags (latest=2.1.201, stable=2.1.185).
  • Documented the Fable 5 redeployment: Fable 5 and Mythos 5 were suspended for all users on 2026-06-12 under US export controls (~19 days) and Fable 5 was restored globally on 2026-07-01 with an improved safety classifier targeting the reported vulnerability-finding behavior; the automatic Fable-to-Opus fallback follows it.
  • Added the Fable 5 plan-usage note (Pro/Max/Team/select Enterprise include Fable 5 up to 50% of weekly usage limits through 2026-07-07, then usage credits) and the Fable 5 vs Mythos 5 distinction (Mythos 5 has no classifiers and is Project Glasswing invitation-only, not selectable via /model).
  • Added v2.1.198–v2.1.201 operating notes: subagents run in the background by default (v2.1.198), Claude in Chrome GA, /dataviz skill, SSL/streaming/subagent fixes (v2.1.199), default permission mode "Manual" (v2.1.200), and Sonnet 5 mid-conversation system-role removal (v2.1.201).

2026-07-01

  • Updated the English handbook baseline to Claude Code v2.1.197 after checking the official changelog and npm dist-tags (latest=2.1.197, stable=2.1.185).
  • Reflected Sonnet 5 as the current Sonnet path in Claude Code: Anthropic API sonnet maps to Sonnet 5, Pro/Team Standard/Enterprise subscription seat defaults use Sonnet 5, and Sonnet 5 supports native 1M context plus low through max effort.
  • Added v2.1.191~v2.1.196 operating notes for organization default model labels, clickable file attachments, .mcp.json self-approval hardening, background job transcript preservation, PowerShell git command exit-code handling, Remote mid-turn crash recovery, and background agent/plugin validation fixes.

2026-06-25

  • Updated the English handbook baseline to Claude Code v2.1.190 after checking the official changelog and npm dist-tags (latest=2.1.190, stable=2.1.179).
  • Added v2.1.181~v2.1.190 operating notes for sandbox.credentials, destructive-command sandbox auto-approval, Windows PowerShell sandbox fixes, MCP login/logout, MCP idle timeout, misleading MCP status fixes, non-interactive fallback reliability, output-schema determinism, Korean paste handling, and app/schema bug fixes.
  • Refreshed model guidance for model restriction and deprecation-warning behavior: main model restrictions center on Opus/Sonnet/Haiku/Fable families, Haiku remains subagent-only for this path, and deprecated models should trigger warnings.
  • Refreshed subagent/background guidance for the three-level nesting cap, nested-agent stability, Agent deny rules, and background permission-prompt handling.

2026-06-13

  • Fixed English locale internal links so they no longer leak to the Korean edition: the cross-references to the subagents chapter (in the context page) and the plan-mode chapter (in the multi-session page) now point to /en/books/... instead of bare /books/....
  • Editorial review pass with no content, model, or policy changes for this handbook.

2026-06-10

  • Updated the English handbook baseline to Claude Code v2.1.170 and Claude Fable 5.
  • Added fable and best alias guidance, including the fact that Fable 5 is not the default and requires v2.1.170 or later.
  • Documented Fable-specific automatic fallback to Opus, --safe-mode troubleshooting, Fable data-retention/thinking constraints, and ANTHROPIC_DEFAULT_FABLE_MODEL.
  • Added fallbackModel chain guidance for overload or availability failures before long autonomous sessions.
  • Added detailed v2.1.169 operating notes for /cd, self-hosted runner post-session hooks, and bundled skill/workflow disabling.
  • Added the v2.1.170 transcript persistence fix for sessions launched from VS Code integrated terminals or shells inheriting Claude Code environment variables.
  • Kept Opus 4.8 as the default high-capability Opus path and clarified when to use Fable, Opus, Sonnet, and Haiku.

2026-05-29

  • Updated the English handbook baseline to Claude Code v2.1.154 and Claude Opus 4.8.
  • Added current model alias guidance: Anthropic API, Claude Platform on AWS, and Bedrock/Vertex/Foundry resolve opus and sonnet differently.
  • Documented /model default-saving behavior, resumed-session model preservation, and full model name pinning for reproducible work.
  • Added Agent View, background sessions, claude --bg --exec, dynamic workflows, /goal, and /workflows to the operating model.
  • Added current command guidance for /usage-credits, /reload-skills, /run, /verify, /run-skill-generator, /code-review, and the updated /simplify role.
  • Added headless notes for --session-id, background-session automation, app-level verification, and nonessential-traffic controls.

2026-05-05

  • Added the first English locale handbook: Claude Code Complete Guide.
  • Registered claude-code-advanced under the English content tree.
  • Documented the expected behavior for unsupported English handbook routes.
  • Added English titles, descriptions, chapter labels, and internal links.

Editorial Policy

The English edition is localized by book, not by global fallback. A book becomes available in English only when its English content tree is present and registered.

This prevents Korean content from appearing under English URLs and keeps search, sitemap, home, and preview behavior aligned with actual content availability.

Related docs

Release coverage history

Claude Code Command Master · Claude Code: Dated release coverage and handbook update decisions, preserved separately from current instructions.

Verification Report

Verification checklist for the English Claude Code handbook locale.

Cmd. /model

Claude Code Command Master · Saves the selected model as the default for new sessions. Press s on a picker row, or use a supported -p invocation, for a session-only change.

Earlier verification records

Claude Code Command Master · Claude Code: Earlier review dates, version baselines, and findings, with a link to the current verification scope.

Plan and Environment Setup

Prepare Claude Code plans, installation, update policy, and a safe repository baseline.

Verification Report

Verification checklist for the English Claude Code handbook locale.

On this page

2026-10-23 · Claude Code 2.1.308October 10, 2026 release refreshOctober 7, 2026 release refresh (previous)September 26, 2026 release refresh (previous)September 12, 2026 release refresh (previous)2026-09-052026-08-282026-08-202026-08-032026-08-012026-07-102026-07-042026-07-012026-06-252026-06-132026-06-102026-05-292026-05-05Editorial Policy