Claude Code v2.1.310: a Monitor tool for background work, retries that drop a rejected beta#

Published by

Part of the Claude Code Version Tracker series. | Official Env Vars | Official Changelog

Claude Code v2.1.310, the release after v2.1.309, adds a Monitor tool and plugin monitors on Bedrock, Vertex, and Foundry; Monitor streams events from a background process, one notification per stdout line.[1] It also retries requests a gateway rejects by dropping the effort-2025-11-24 beta or mid-conversation system messages, and stops background cleanup from deleting recent pasted images when cleanupPeriodDays is very large.[1]

A Monitor tool for background processes#

The Monitor tool streams events from a background process: each stdout line arrives as a notification. For a one-shot "wait until done," Bash still applies; for a running stream of events, Monitor does.[1] A companion read, get_task_output, reads the output of a shell or Monitor task by its task_id in the session.[1]

Plugin monitors are background watch scripts the host arms as persistent Monitor tasks, unsandboxed and at the same trust tier as hooks, so a plugin need not instruct the model to arm them.[1] The changelog scopes the Monitor tool and plugin monitors to Bedrock, Vertex, and Foundry, and to sessions where telemetry or nonessential traffic is disabled.[1]

In those same environments, long foreground sleeps are now blocked. The error is specific: "Long leading sleep commands are blocked. To poll until a condition is met, use Monitor with an until-loop."[1]

Retries that drop a rejected beta or system message#

When a gateway or compatible server rejects the effort field or the effort-2025-11-24 beta value, Claude Code resends the request without either, and will not send either to that model again for the rest of the process.[1] A parallel path covers mid-conversation system messages: when a server refuses a request where a system message sits, it retries once without the system messages.[1]

This release also adds CLAUDE_CODE_RETRY_WATCHDOG_SCOPE, a knob on the existing retry watchdog. With the watchdog on, its guarded branch runs unless the scope is set to capacity, which turns that branch off.[1]

The bug-fix sweep#

  • Background cleanup no longer deletes recent files, such as pasted images, when cleanupPeriodDays is set to a very large value.[1]
  • Compaction after a "Prompt is too long" error no longer keeps too much of a conversation with dense text, such as base64 or SVG, which could fail the next request again.[1]
  • File read permission prompts now show where a symbolic link leads.[1]
  • A question's auto-continue timeout no longer fires the moment an external editor closes after a long edit.[1]
  • Non-interactive sessions (-p, Agent SDK) use less memory during compaction when the transcript file is very large.[1]
  • Auto mode's prompt before the first read outside the working directories now says when blocking those reads makes shell commands ask for permission.[1]

New Environment Variables#

VariableWhat It Does
CLAUDE_CODE_RETRY_WATCHDOG_SCOPERead alongside CLAUDE_CODE_RETRY_WATCHDOG. With the watchdog on, the guarded branch runs only when this is not set to capacity; setting it to capacity turns that branch off. New in v2.1.310.
CLAUDE_CODE_DESKTOP_CONNECTOR_NAMESCarries desktop connector names into the session from the host. It is read once at startup, applied, then cleared from the environment. New in v2.1.310.

The way to wait is now a Monitor loop, not a sleep#

Monitor is the handle for a background process that keeps emitting: it turns each stdout line into a notification, and get_task_output reads back what a shell or Monitor task has produced. Where it is available, a command that would once have polled with sleep is refused, and the error points at a Monitor until-loop instead.[1]

That changes how a session ends. A persistent Monitor task holds the turn open after other background work finishes, the way a scheduled wakeup does, so a session can keep running on a stream rather than closing.[1] Because plugin monitors are armed by the host at the trust tier of hooks, that watch runs without the model deciding to start it.

Sources#

  1. Claude Code Official Changelog, v2.1.310 release notes

This analysis is conducted for educational and research purposes under fair use principles. All trademarks and software referenced belong to their respective owners.

Let's Connect

BlueskyLinkedInThreads

Previous Claude Code analysis: v2.1.309 (October 22, 2026)

All 80 Claude Code analyses: Claude Code Version Tracker · Official Claude Code changelog

← Back to all posts