Claude Code v2.1.274

What

• A new control-protocol message, set_chrome_browser_hints, lets a remote or gateway host tell the built-in Chrome browser extension (used for browser automation) which device to prefer on a given machine, including a preferred device ID, a list of local device IDs, and the host platform. This is stored per remote session.
• A new browserHints state (preferred device ID and local device IDs) is threaded through the extension-pairing and device-detection logic, powering a rewritten selection helper that automatically picks a persisted device, the only connected extension, or the sole local candidate, or otherwise asks the user to choose.
• When asking the user to pick a browser, Claude Code now groups the choices into "Browsers on this computer" and "Other connected browsers," always offers a "switch to a different browser" option, and is instructed to always ask when the choice is ambiguous.
• The list_connected_browsers tool now reports an onThisComputer flag (a more reliable signal than the previous "is local" heuristic) and an inUse flag marking which browser the session's actions currently target, plus readable platform names (macOS, Windows, Linux, etc.) instead of raw platform strings.
• New helper text tells Claude when a browser was auto-selected (no need to ask the user) versus when it must ask, and a new reportBrowserSelected telemetry event records the outcome along with how many browsers were connected and how many were local.
• A new timeout message for unresponsive tool calls now mentions that Chrome might be asleep on another computer, depending on whether a routing acknowledgment was received.

Why With several Chrome browsers or computers potentially connected, these changes reduce unnecessary prompts by remembering and auto-selecting the right browser when possible, while making it clearer which browser is in use and giving better options when a manual choice is genuinely needed.

What

• The team-memory sync system now reports a specific reason when it can't load a shared memory basis, such as the store being empty, unreadable, mismatched, or over a size cap, instead of just failing silently.
• A new account scope is recognized in several sync checks, for example skipping local-write-preservation checks and allowing pulls even when the walk found nothing.
• The check that stops memory files from being written outside their allowed mount directory (an escape check) is now scope-aware, handling user, account, and team scopes differently through a shared helper.
• If the server refuses to save one particular file during a sync, that file is now marked as refused and skipped on retries for a while, while the rest of the sync continues; the file stays local only and its changes will be lost if the machine is recycled. The sync result reports how many files were refused.
• The internal state Claude Code tracks during a sync now includes fields for refused writes and for whether the shared basis is unusable.

Why These changes make multi-device team memory sync more resilient: one problematic file or an unreadable shared store no longer breaks the whole sync, and the system can explain more precisely what went wrong.

What

• Reading an asset from an artifact (read_asset) now supports a distinct "public read" path used when the requester is outside the artifact owner's organization. The read result gains a public_read/public marker, the underlying fetch function takes a new admitPublicRead callback and returns publicRead in its result, and a dedicated public_refused error reason covers the case where a public artifact doesn't serve that asset to outside readers.
• A companion refusal path gains a public_outside_org case, returning the same message text used in the resume_replies flow. Share-status records now also track an outsideOrgReader flag, cleared whenever the account boundary changes, alongside the existing probeErrorCode and role fields.

Why This gives artifacts a defined public-read path for people outside the owner's organization, with clear refusal messages when that access isn't available, instead of treating all outside-org reads the same way.

What

• A new sessionInboxPointers tracker records queued messages: when a remote/bridge control message or a remote-origin user message is queued, it's registered via noteQueued with its origin, wake state, and id.
• When the session goes idle, queued file/attachment ids that a remote bridge peer never fetched are now re-sent via renotifyUnfetched, both from the idle-nudge path and a new onIdleReported callback.
• Session setup now also taps into command lifecycle events via this same tracker.

Why This makes message and attachment delivery to a remote/bridge peer (such as a companion device or connected session) more reliable, ensuring items that were queued but never picked up get another chance to be delivered instead of silently sitting unfetched.

What

• Writing a file or asset (an artifact's underlying content) to a location outside consented organization locations is now explicitly refused, with reasons like file_outside_org_unasked, asset_outside_org_unasked, or asset_copy_outside_org_unasked, and a new artifact_outside_org_consent telemetry event records it.
• Reading the HTML page of a public artifact from outside your organization now goes through an admitPublicRead approval check, which defaults to refusing; without explicit approval, the read is blocked instead of silently fetched.
• The artifact file-read path no longer gives one generic 403 message for all outside-org reads. It now distinguishes cases: for a "publicFile", it explains the bytes aren't returned inline but can be saved to disk via a tool instead; for a "publicUnasked" case (nobody could be asked for consent), it gives a specific explanation and logs telemetry marking the request refused. The approval check itself is now wired to a real permission-aware function that considers prior grants, whether a human started the turn, and the current mode (for example, plan mode).

Why

This prevents artifacts from being silently written to or read from outside boundaries your organization has consented to, while giving clearer, case-specific explanations instead of one blanket block, and still allowing access once consent has actually been granted.

What

• The artifact-publish logic gained a "stale version guard" that denies publishing (with reasons like stale_version_guard or stale_version_guard_before_card) when the session hasn't read or published the artifact recently, along with new consent wording for publishing artifacts outside your organization and a check that affects when a publish can be auto-approved.
• A related guard now runs specifically when the client's tracked base version is defined but known to be stale ("behind") relative to the live version: it re-reads the artifact tagged as "known_behind", and if that read still resolves to real text, the publish is refused with reason code known_behind instead of silently overwriting the newer live version.

Why

This prevents a session from accidentally overwriting someone else's newer changes to an artifact when its own local copy of the version is out of date.

What The internal frame-tunnel request helper previously allowed requests to the 'frame' host with no authentication at all. It now requires 'session-jwt' authentication: requests must carry a session JWT (a signed token tied to the current session). Other headers are stripped from frame-tunnel requests, and only the Authorization header captured for the session-jwt case is re-applied.

Why This closes a gap where frame-tunnel requests could be made without any authentication, ensuring they're now tied to an authenticated session.

What

• The set of typed API error kinds grew by about 20 new entries, including effort_requires_thinking, advisor_incompatible, tool_history_mismatch, autocompact_thrashing, pdf_too_large, pdf_password_protected, no_response, tls_untrusted_ca, gateway_content_type, provider_credentials, gateway_signin_required, gateway_session_expired, api_key_auth_disabled, org_disabled_credential, invalid_credential_header, model_requires_usage_credits, long_context_credits_required, consent_unanswered, no_allowed_fallback, model_substitution_disabled, and field_not_granted.
• Two new companion fields were added: api_error_params (holding details like effort, provider, or remedy) and api_error_code (a passthrough of a server-provided error code), letting tools built on Claude Code react to the specific cause of an error instead of parsing its message text.
• api_error_code is now included in turn-completion telemetry (the SDK's assistant message / turn-result data) alongside the existing api_error_status, carrying the server's error code when a turn ends on an identifiable API error.
• Error message objects used to render API errors in chat now carry api_error_params and api_error_code end-to-end, alongside the existing api_error field.

Why

This gives tools and interfaces built on Claude Code a reliable, structured way to detect and handle specific error conditions, such as needing more usage credits or an untrusted TLS certificate, instead of having to guess based on error message wording.

What

• The read-permission checker now has an explicit branch for content flagged as outside the user's organization (outsideOrg), returning a foreign_read decision tagged about: "outside_org" before falling through to the existing owned/network-off checks.
• New guard text distinguishes three situations when such a foreign-org read or copy is blocked: nobody was asked and it should be retried, nobody can be asked in this session so it shouldn't be retried, or a PermissionRequest hook (an automated rule that answers permission prompts for the user) already answered on the user's behalf. In that last case, Claude is told that only the user's own approval actually allows the read, and to inform the user that their hook auto-answered.

Why This closes a gap where an automated permission hook could silently approve access to another organization's artifact; Claude now knows to flag that to the user rather than treating the hook's answer as sufficient.

What

• The self-hosted runner's inference-token auto-refresh logic was rewritten. It now tracks the token's time-to-live (ttlMs, 30 minutes by default), and retries failed refreshes with exponential backoff plus jitter (a random delay) instead of a fixed interval.
• Tokens nearing expiry get a separate, shorter retry window (expiredRetryMs).
• A new error classifier distinguishes errors worth retrying from ones that aren't: a new RemoteConfigWithoutInferenceAuthError, or an HTTP 401/403, is treated as non-network and not retried early.
• A new onResultApiError callback lets a 401/403 returned by the model API during a child session's turn trigger an immediate, out-of-band token refresh (refreshNow()) instead of waiting for the next scheduled refresh.

Why This makes token refresh more resilient to transient failures while reacting immediately to real auth failures, so a self-hosted runner recovers faster from an expired or rejected inference token instead of a child session stalling until the next scheduled refresh.

What

• Permission checks for the artifact database's read_db/write_db actions now consider whether the call is a served/background call, whether it's a multi-entry batch, and the current permission mode, instead of always requiring human approval.
• The same actions gained a new safety check that flags a decision with a "suspicious Windows path" classifier when a risky path condition is detected.
• Other artifact actions, deleting an asset (delete_asset), creating from a type, and publishing, now compute approval the same context-aware way, also factoring in whether the artifact is already owned or consented to, instead of a hardcoded "must be a human" rule.

Why This lets routine, low-risk artifact operations proceed automatically in more cases while still requiring human approval when the context is riskier (unusual paths, non-batch human-initiated calls), reducing unnecessary approval prompts without loosening protection where it matters.

What

• Removing a git worktree (for example via the claude rm or ctrl+x flow, or automatic agent-worktree/job cleanup) now checks for work inside submodules, not just the top-level worktree. A new submoduleWork concept distinguishes "unverifiable" submodule state (such as a nested repo or an unconfigured gitlink) from ordinary uncommitted "changes" inside a submodule.
• When submodule work is unverifiable or has changes, worktree removal now refuses to proceed and shows a message naming the issue explicitly, with tailored explanatory text and follow-up instructions for each case; job deletion can likewise keep a worktree around for this reason.
• The confirmation dialog shown before discarding uncommitted changes in a worktree now separately calls out submodule work that a plain git status in the worktree wouldn't reveal.
• Before counting changes, the "exit worktree" confirmation dialog now also checks the worktree's git configuration for unsafe settings (such as conditional includes or custom LFS transfer agents); if the worktree can't be safely read, it shows a generic "uncommitted files that could not be counted" warning instead of a count, and checks submodules via a --submodule=short diff, adding a warning line if a submodule can't be checked.
• The JSON snapshot of git worktree state sent over the remote bridge now includes a submodules_unverified field alongside existing fields like head_sha, unpushed_count, and is_dirty.

Why Submodule changes don't always show up in a normal git status of the parent worktree, so without these checks a worktree could be deleted while it still held uncommitted or unverifiable work inside a submodule. This makes worktree removal safer and more transparent about what it could and couldn't verify.

What

• The policy helper (which manages settings pulled from a remote/managed source) now remembers the last failure code it saw and only announces a tier change when the failure changes, not every time it fails.
• apply() and retireState() reset the tracked failure (and reset selectedEntry when retiring).
• The mid-session re-check also announces a tier change when the failed config itself changes, not just when other conditions change.

Why Previously, a stuck policy-helper failure could re-trigger the "tier changed" announcement on every retry tick, creating noise. Now it fires once per distinct failure, giving a more accurate signal about when something actually changed.

What

• Many request/auth error branches in the API-error formatter now attach a machine-readable apiError code (and sometimes apiErrorParams) alongside the existing human-readable message. This covers tool-use concurrency conflicts, duplicate or orphaned tool_use ids, using an effort setting without thinking enabled, advisor-model incompatibility, disabled API-key auth, and provider credential failures for Bedrock, Vertex, and Foundry (which now include a remedy param).
• The catch-all error handler now classifies more failure modes with their own typed apiError codes instead of lumping them into a generic error: no_response, tls_untrusted_ca, gateway_content_type (a Bedrock proxy rewriting the event stream), provider_credentials (with apiErrorParams: {provider, remedy: 'host_managed'}), and gateway_signin_required/gateway_session_expired (with remedy: 'gateway_token' when the token came from the environment). Previously most of these produced a generic server_error/unknown message with no machine-readable cause.

Why Typed error codes let tooling and error handling react to the specific cause of an API failure instead of just showing a generic message, making it easier to tell the user what went wrong and how to fix it.

What

• Org login/managed-settings validation failures now carry a machine-readable reason (for example managed_settings_invalid or org_pin_api_key_conflict) and a policyUnreadable flag, in addition to the existing human-readable message.
• When managed settings are unreadable or invalid, or a policy refusal state exists, Claude Code now sends a dedicated telemetry export (using OTel, a tracing/telemetry standard) that force-flushes with a timeout, rather than relying on general telemetry.

Why The structured reason and flag let tooling distinguish specific managed-settings failure causes instead of parsing free text, and the dedicated telemetry export makes it more likely that failure data reaches the server before the process exits.

What

• A new flag tengu_swirling_meteor controls whether task-stop notifications from background agents get coalesced (merged together) during a session's live loop.
• Print/headless mode gained a coalesceTaskNotifications option and a new print_task_notification_coalesce telemetry event, tracking how much held completion text and workload is batched.
• The session's message-queue engine gained a coalesceTaskNotifications callback: when enabled, a queued task-notification whose text fits under a length budget is merged into the pending turn instead of being sent out as a separate message. This path is currently gated off by default.

Why

When several background tasks (like background agents or shell commands) finish around the same time, Claude Code can now group their completion notifications into one update instead of interrupting the session repeatedly.

What

A new tracking system keeps a per-session record (heardVersions) of the newest version of a watched Artifact that has been "heard" from elsewhere, and compares it against the version the current session has itself published, to determine if the session's local copy is behind. A "told" flag avoids repeating the same notice more than once.

The messaging shown to Claude changed accordingly: instead of always saying "Claude will be notified when this artifact is republished," it now branches on whether live tracking is active, in which case it says "Claude will keep track of new versions of this artifact published elsewhere."

Why

This replaces an active notification model with a passive one: rather than interrupting a turn to announce a republish, Claude Code quietly remembers what version it last heard about and only flags it as stale when relevant, avoiding duplicate notices.

What

• MCP auth failures are now classified into two distinct kinds: credential_rejected (a flat, generic rejection) and a new step_up, which covers a 403 "insufficient_scope" response. This classification is handled by a new shared function/classifier instead of duplicated inline checks.
• When an MCP tool call gets a 403 insufficient-scope error, Claude Code now surfaces a specific message asking you to re-authenticate for the additional permissions needed, rather than treating it like a generic expired or rejected credential.
• Whether a step-up is pending is tracked per MCP client connection (via pendingStepUpScope), and this pending state is now properly cleared: when a fresh 401 (not 403) response is seen, when the underlying credential itself disappears (for example, "no token data found" or "token expired without refresh token"), and it's now only checked/set when the original request actually carried an Authorization header.
• The auth-challenge interceptor now also ignores responses to requests that had no Authorization header at all, and parses the WWW-Authenticate header's scope through a shared helper instead of inline regular expressions.

Why Previously, an MCP server asking for additional OAuth permissions looked the same as a fully rejected or expired credential, so Claude Code could only tell you to "re-authenticate" without saying why. Now it can tell you specifically that more permissions (scope) are needed, and correctly resets that state once you've re-authenticated or the credential changes.

What

• New, frozen sets of environment variables are applied to internal git invocations: GIT_ALLOW_PROTOCOL="none", GIT_NO_LAZY_FETCH="1", GIT_NO_REPLACE_OBJECTS="1", GIT_TERMINAL_PROMPT="0", and, unless SSH is explicitly allowed, GIT_SSH_COMMAND="false".
• The internal git command-construction helper gained a new allowGitTerminalPrompt option; unless a call explicitly allows it, GIT_TERMINAL_PROMPT is stripped from the environment passed to the git subprocess, whereas before it could pass through unfiltered.
• Git push calls used internally (for worktree operations and plugin tag creation) now explicitly set allowGitTerminalPrompt: disabled for background worktree pushes, enabled for interactive plugin tag pushes.

Why

This reduces the risk of internal git commands silently reaching the network, replacing objects, or hanging on an interactive credential prompt, while still allowing prompts in the specific cases where a human is present to answer them.

What

• New code scans a working tree's git index (and any nested .gitattributes files) for files tracked with filter=lfs (Git Large File Storage), checks whether they were checked out as literal LFS pointer files rather than real content, and surfaces a warning telling the user to run git lfs pull if so.
• Marketplace add/refresh logic was restructured around a shared clone helper, whose result now feeds a new step that logs and reports this git-LFS warning after the clone completes, replacing the old approach of passing a skipLfs option inline to the clone call.
• The --skip-lfs marketplace option's description was rewritten to clarify it now has no effect: Claude Code's own git never downloads LFS content regardless of the setting, LFS-tracked files are always checked out as pointers, and getting the real content requires running git lfs pull manually in the marketplace checkout.

Why

This makes it clear to users when marketplace plugin files are just LFS pointer stubs rather than real content, and clarifies that --skip-lfs doesn't need to be set since LFS content is never fetched automatically anyway.

What

The help text and behavior around watching an Artifact (a published file Claude Code can track for changes) has changed:

• The tool description no longer says that a republish from elsewhere "arrives as a notification telling you to re-read it before editing."
• It now says a republish elsewhere "starts no turn and sends no notification."
• Instead, Claude Code silently keeps track of the artifact's version in the background.
• The next time the artifact is read or a publish is attempted, the result is prefixed with a warning telling Claude a newer version exists, and instructing it to re-fetch the URL and merge its edits onto that version.
• The description also explains what to do if a publish is rejected because the artifact changed underneath it.

Why

Previously the description implied a republish elsewhere would actively wake the session with a notification, which wasn't accurate. The new wording sets correct expectations: nothing interrupts the current turn, but the next read or publish attempt will catch Claude up and prompt it to merge its changes onto the latest version instead of overwriting it.

What

• The terminal's status dialog schema now includes an optional memories field, listing saved auto-memory entries drawn from the MEMORY.md index and each file's modification time, capped at 200 entries.
• The status call that reports auto-memory/auto-dream status now also returns a memories array whenever memory folders are present.
• A new schema describes a single memory entry: its name (a relative path, or "MEMORY.md" for the index file), its absolute path, an optional description and type (user, feedback, project, or reference) from its frontmatter, and its last-modified time.
• The get_memory_dialog control-protocol response, used by hosts that build their own /memory UI, now includes this same memories array alongside the existing folder list.

Why Tools and custom UIs built on top of Claude Code can now show users exactly which memories are saved, with descriptions and types, instead of only folder-level summaries.

What

• The effort-selector UI can now show a note that the organization pins the starting effort for new sessions on a model, separate from the existing note about the organization's overall default effort.
• When a user picks an effort level that ends up capped, the confirmation message can now explain that even though their choice was saved, the organization forces new sessions on that model to start at a different effort.

Why This clears up potential confusion where a user's saved effort preference doesn't match what a new session actually starts at, by explaining that the organization controls the starting point separately from the general default.

What

• The authentication-required error message changed from "Claude Code web sessions require authentication..." to "Claude Code cloud sessions require authentication...".
• Menu descriptions changed from "launch in Claude Code on the web" to "launch in a cloud session", including the remote-control disable option.
• Ultraplan's user-facing wording was updated the same way, including its refine-prompt option and its startup message.

Why

Keeps terminology consistent across the product now that sessions can run in the cloud, so users see the same term everywhere instead of an older, more specific phrase.

What

• Adding an MCP server via config now checks its transport type against a host-only set (sdk, sse-ide, ws-ide) and throws a clear error explaining that such servers are registered by the host application at runtime and can't be stored in configuration.
• When processing an mcp_set_servers update, servers of type sse-ide or ws-ide are now routed into the blocked/dropped map alongside already-registered names, instead of falling through to the general allow/block logic.

Why These transport types represent servers that only make sense as live, host-managed connections (such as an IDE's own SSE/WebSocket endpoint), so storing or generally allow/block-listing them as regular config entries doesn't make sense; this change makes that restriction explicit and consistent.

What

The self-hosted-runner gateway process now tracks how many client requests are currently open compared to how many it is able to forward upstream at the same time. When the number of open requests exceeds the configured (or default) outbound concurrency limit, it logs a rate-limited warning.

The warning suggests either adding more replicas or raising BUN_CONFIG_MAX_HTTP_REQUESTS, along with the replica's memory limit, to allow more concurrent outbound requests.

Why

This helps operators running a self-hosted gateway notice and diagnose a bottleneck before it causes request failures or timeouts, and points them directly at the two knobs (replica count and BUN_CONFIG_MAX_HTTP_REQUESTS) that can relieve it.

What

• When 1M-context usage requires usage credits, the guidance message now checks whether the session is non-interactive or self-hosted-like, and whether the extra-usage-credits command is actually available (which itself depends on the DISABLE_EXTRA_USAGE_COMMAND setting). Depending on the result, the message either offers the /usage-credits command or only mentions /model.
• Similarly, when a requested model isn't available, the suggestion of switching via /model versus the --model flag now takes into account whether the session is interactive, and whether it's running in contexts like the SDK, CLI, or claude-code-github-action.

Why

Previously these suggestions could point users toward commands or flags that don't actually work in their current context (for example, suggesting an interactive /model command inside a non-interactive script or GitHub Action). The messages now match what's actually usable in the situation.

What

When a session is configured with SDK MCP servers (external tool servers set up through the SDK), the first query of a turn now waits for any of those servers that are still connecting, instead of immediately proceeding without their tools. A new tracker keeps a list of configured-but-not-yet-connected servers and the turn logic waits on it before continuing.

The wait is bounded by the existing MCP connect timeout (default 5 seconds). Claude Code logs whether the wait timed out and which servers were still pending. If a server still hasn't connected once the wait ends, the turn proceeds without that server's tools and a warning is shown.

Why

Previously a turn could start before slow-to-connect MCP servers were ready, silently missing their tools for that turn. This change gives those servers a short grace period to finish connecting, reducing the chance that a tool is unexpectedly unavailable just because it hadn't connected yet.

What

• The artifacts quickstart tool now advertises that, when possible, it saves the matched artifact type's published files (and, for slides or design intents, the default design system's files) to the session's scratchpad and lists them, rather than only reading titles, descriptions, and README text.
• The design-system/start-kit save path now returns more specific reasons when files aren't saved, such as "list the files yourself" or "read with your own calls" instead of a generic fallback, and separately tracks whether a REPL tool is available in the tool pool from whether start-kit mode itself is enabled.

Why These changes make it easier for Claude to reuse saved design-system files directly and to understand why a save didn't happen when it fails, instead of guessing.

What

The logic controlling fast mode (internally called "penguin mode") was changed in a few ways:

• Organization-status handling for fast mode is now split depending on whether the session is an SDK-style context, using new helper logic.
• A per-session opt-in check gained a sessionOnly parameter.
• A new auto-trigger prefetches the organization's fast-mode status whenever settings show fastMode=true but the org status is still pending or assumed disabled.
• Separately, the policy override gate for fast mode now applies whenever policySettings.fastMode === false, even if the caller did not explicitly request fast mode for that request; previously this override only took effect when fast mode had already been requested.

Why

These changes make fast-mode eligibility checks more consistent across SDK and non-SDK contexts and ensure an organization policy that disables fast mode is enforced even when a particular request didn't ask for fast mode, closing a gap where the override could be skipped.

What

• Internal git helpers used for the "teleport" feature (upstream-set, branch checkout, current-branch lookup) now resolve a stable checkout root via a new helper and pass an explicit working directory and environment to every git subprocess, instead of relying on the process's ambient working directory.
• A new verification step checks that the checkout's .git entry actually points back to the resolved repository, throwing an error ("Could not verify this checkout's git repository") if it doesn't.
• A new auto-stash helper stages untracked files and runs git stash push --message, backing a new "Teleport auto-stash" flow that stashes uncommitted changes before teleporting.

Why

This prevents teleport's git commands from accidentally acting on the wrong repository or directory, and avoids losing uncommitted work by stashing it automatically before switching.

What

• The dedup logic that decides whether a project-thread message notification needs re-processing ('judged' messages) now hashes the message text and stores it alongside the existing id and timestamp used as the dedup key.
• The same text-hashing approach was applied to 'other comments' shared state, and to artifact autoreact logic, using matching helper functions.
• A new textsForgotten flag and a lastText map track when a comment's or message's content has changed since it was last judged or reacted to.

Why

Previously, dedup was based only on a message's id and timestamp, so if a message or comment was edited but kept the same id and timestamp, it was wrongly treated as already-seen and skipped. Hashing the actual text means edited or resent content is now correctly detected and re-processed.

What

• The fetch wrapper that retries a request after a 403 response with a sent bearer token now also requires a new check (Nk) to pass, in addition to the existing check that the response was a 403 with a token sent.
• The same check now gates whether a 403 response gets turned into a needs_consent design-MCP error, restricting that behavior to first-party design MCP endpoints.

Why This narrows when the 403-retry and design-consent behavior kicks in, preventing them from firing for responses that aren't actually from the first-party design MCP service.