Claude Code v2.1.311 Release Notes — What's New

What's changed

Added --hold-idle-file and --max-hold-min to self-hosted-runner, to keep an idle session while your host reports processes it left running
Added a tip for the Explanatory output style, shown when you ask Claude for explanations
Fixed long freezes at startup and after reading or editing files when a CLAUDE.md file holds a very long list item
Fixed interrupting Claude not taking effect until a timeout while an MCP server had not answered a resource read or a skill was still downloading
Fixed standard-context sessions stopping with "Usage credits required for 1M context" when a request ran over 200K tokens; Claude Code now compacts the conversation and continues
Fixed Write and Edit stalling for up to 5 seconds after they ran, and reporting 0 lines changed, when changing thousands of lines in a file
Fixed subagents being unable to use MCP tools from servers that finish connecting after the subagent starts
Fixed Claude seeing stale MEMORY.md and CLAUDE.md content right after automatic compaction when those files were edited earlier in the session
Fixed claude -p and SDK sessions saving transcript messages out of order or keeping messages that were taken back
Fixed SubagentStop hooks running about twice a minute for each running subagent instead of once when it finishes
Fixed the @ file picker ignoring .ignore/.rgignore negation rules that re-include git-ignored files
Fixed a subagent's isolated worktree being removed while a background subagent it started was still working in it
Fixed background agents in auto mode that wait on their own shells starting a new main conversation turn on every wake
Fixed the Bash tool description claiming the working directory always persists between calls
Fixed the environment block naming a shell commands don't run in, such as fish when the Bash tool uses zsh
Fixed claude mcp add, claude mcp remove and /mcp naming the current folder instead of the project entry in ~/.claude.json that holds a local-scope server when run below a repository root
Fixed claude mcp list and claude mcp get showing the error code twice on failed-connection lines (for example ENOENT: ENOENT: …)
Fixed Remote Control sessions staying on "Connecting" for about two minutes when a network proxy blocks a startup request
Fixed messages that Claude sends to a cloud or Remote Control session appearing as your own message in the Claude mobile apps
Fixed Claude not being told the cause when a file attached to a message sent over Remote Control or to a cloud session could not be saved because the disk was full, or that a message's attachments past the first 20 were left out
Fixed WebFetch and WebSearch hanging on a stalled response in Cowork cloud sessions; an unfinished request now fails after 300 seconds
Fixed a background session that crashed between turns not being restarted while it was attached, pinned, or had a scheduled task or wake-up set
Fixed the "background service did not respond" error suggesting the disabled claude daemon restart; it now suggests claude daemon stop --any and says it ends background sessions
Fixed claude respawn <id> starting the background service before reporting that no background session matches the id
Fixed /effort not warning about a prompt cache miss in plan mode when the plan model differs from the session model
Fixed /ide saying the VS Code extension was installed before the install finished or when it failed
Fixed the Write tool's file preview skipping rows and miscounting hidden lines when a line is wider than the terminal
Fixed ↑ in an agent's chat tab recalling a message that was still waiting to be delivered, so resending it sent a second copy
Fixed Cowork cloud sessions losing their connectors and most tools after a restart when a plugin or your settings named an agent; Cowork cloud sessions now ignore that setting
Fixed agent teams sessions showing an empty task list when coming back with --resume, --continue, /resume or --session-id, including after /clear or a crash, and /branch writing to the original session's list
Fixed pasting text that mentions an image file, such as ! open /tmp/shot.png or /review look at /tmp/shot.png, attaching the image and dropping its path from the prompt
Fixed the feedback draft card showing its 1/2/0 and Esc shortcuts while the prompt has text, when those keys act on the prompt instead of the card
Fixed a lone backslash in quotes or brackets, like "\" or (\), disappearing from Claude's responses
Fixed agent teammates compacting their history when DISABLE_COMPACT is set
Fixed the rewind menu offering "Summarize from here" and "Summarize up to here" when DISABLE_COMPACT is set
Fixed a finished /code-review, or another skill that runs in a sub-agent, running a second time when a cloud or background session restarts
Fixed long hidden thinking being cut off as idle on Google Vertex AI, Microsoft Foundry and Claude Platform on AWS, where the endpoint sends thinking progress updates
Fixed /ide saying it had installed the JetBrains plugin when nothing was installed
Fixed Claude Pro and Max subscribers being told to ask their admin when their subscription can't be used; the message now points to billing settings
Fixed the diff pane opening by itself after an edit in wide fullscreen terminals when it had nothing to show
Fixed /mcp showing a remote server as failed after "Clear authentication" when the server works without sign-in
Fixed /mcp showing "authenticated" for a remote server that Claude Code sends no credentials to
Fixed a --plugin-dir folder of plugins loading as one plugin when an empty .mcp.json was at its top
Fixed /usage never showing large prompt-cache misses under "What's contributing to your limits usage?"
Fixed status line links staying plain text in background sessions after you open them from a terminal that supports links
Fixed the /rewind confirmation saying the conversation "will be forked" when the later messages are removed from the conversation
Fixed the /rewind warning that wrongly said manual and Bash edits are never affected by a code restore
Fixed plan approval in screen reader mode sending feedback you had dismissed with Escape
Fixed Claude Code retrying requests the API marked not to retry, which could hold a turn for minutes or, in unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG), indefinitely
Linux: Fixed sandboxed Bash commands failing with bwrap: Can't create file when a --plugin-dir folder was also an added directory and permissions.blockReadsOutsideWorkingDirectories was on
Self-hosted runner: Fixed a session failing to start when a rate limit (HTTP 429, or a git wrapper that exits 75) blocks an added read-only repository; it now starts without that repository
Improved startup time for Pro and Max accounts by skipping two network requests on launches within an hour of the last check
Improved /teleport and claude --teleport to warn when a compacted cloud session loads from its last compaction, so the messages it summarized aren't in the local copy
Improved the messages shown when a background session's process exits: they no longer promise a restart that isn't coming, and they say how to resume the session
Improved artifacts with several views: Claude now routes each view on the link's #name and no longer says the address bar stays the same as you switch views
Improved shell commands that reach their timeout: the result now shows the output so far and says the command is still running in the background
Improved compaction: when the model's reply has no summary in it, Claude Code now usually asks for the summary once more before it replaces the conversation
Improved the Artifact tool's choice between a page and a document: explainers and visual or interactive work become artifact pages; documents are for writing people keep editing or pass around

…