Claude Code 2.1.301 stops waiting out distant usage limits

Claude Code's unattended retry mode exists to keep a long job running through failures. A usage limit, though, can reset far in the future, and before Claude Code 2.1.301 the retry loop's answer to that was to keep waiting.

The release notes on Github add CLAUDE_CODE_RETRY_WATCHDOG_MAX_USAGE_LIMIT_WAIT_MS. When it is set, unattended retry mode (CLAUDE_CODE_RETRY_WATCHDOG) ends a request if the usage limit resets too far away, where before it waited. The variable gets the attention, but most of the release is fixes, and a few of them involve credits and data.

The watchdog now has a ceiling on how long it waits for a usage limit

The watchdog itself is fairly new. A documentation issue on GitHub says v2.1.186 capped CLAUDE_CODE_MAX_RETRIES at 15, and that the release told anyone running unattended sessions to use CLAUDE_CODE_RETRY_WATCHDOG instead. The same issue notes that the docs did not describe the watchdog at all. It also quotes the official Errors page: Claude Code retries transient failures such as server errors, overloaded responses, request timeouts, temporary 429 throttles and dropped connections "up to 10 times with exponential backoff", with CLAUDE_CODE_MAX_RETRIES defaulting to 10.

A third-party internals explainer from Helmcode describes how that loop works. By its account the base delay is 500ms, doubling with each attempt and capped at 5 minutes, 429 responses honor retry-after headers when present, and the counter is per API call. Helmcode also describes an unattended mode with indefinite retries, a 30-second heartbeat that keeps the process alive and a 6-hour hard cap. That is an outside description, and it may predate the watchdog in its current form.

So why would a retry wait for so long? A troubleshooting guide from Ofox says subscription limits are two independent caps: a rolling 5-hour window that starts with your first message and a separate 7-day weekly cap, which can run out while the session bar still looks low. Ofox adds that nothing you do inside a session brings a weekly cap back early, lists auto-accept and background loops among the causes of overnight quota spikes, and treats the Pro and Max "usage limit" wall as a different failure from a 429 on an API key. Going by Ofox's description, a retry blocked by the weekly cap could be waiting on a very distant reset.

The new variable sets an upper bound on that wait in milliseconds. The release notes give no default.

Before → after

• Switching to a model with a smaller context window: before, it could spend usage credits on a summary by the previous model without asking first; now a conversation too long for the new model is summarized by the previous model first, and the bug is listed as fixed.
• Quitting with a worktree made by a WorktreeCreate hook: before, Claude Code removed it without asking; now it asks when the worktree may hold unpushed commits.
• OpenTelemetry tool_decision events: before, auto mode classifier decisions could not be told apart from permission rules; now they carry classifier_verdict and permission_mode, plus classifier_category naming the built-in rule a classifier block matched when OTEL_LOG_TOOL_DETAILS=1.
• Grep and Glob: before, a search program that failed before returning results produced "no matches"; now they return an error saying the search failed.
• Workflow agents: before, some skipped their step after reading the harness note that their task text carries no user authority, and the run still reported success; that is fixed.
• LLM gateways whose responses name a different model: before, conversations were compacted over and over on a model you didn't pick; that is fixed.
• The fable and best aliases: before, they errored on the Anthropic API when the newest Fable model was not available to your organization; now Claude Code retries once on the previous Fable model.
• A full disk: before, it surfaced as a misleading "Please run /login"; now the error names the disk and says to delete files.
• The Read tool: before, it read binary files such as .xlsm, .parquet, .epub and .heic as text; that is fixed.
• A tool call cut off by a message sent mid-turn during its permission check: before, the model was told the user rejected it; that is fixed.
• Skills and commands with very many or very long argument names: before, they stalled for seconds; now only the first 64 names, each up to 64 characters, are filled in.

Mods change behavior in two places. A mod hook's .catch handler runs only when the hook throws or times out, and $.env.set resolves with {} once the variable is set or unset, or with { deny } saying why the write was not made. Mods arrived in v2.1.287, as we noted in our October 5 item on 2.1.290. Vim mode gains the % motion, alone or with d, c or y, and VS Code gets LaTeX math rendering.

Retries and telemetry have been moving release by release

The retry settings keep multiplying. On October 6 we reported that 2.1.292 added CLAUDE_CODE_OVERLOADED_RETRY_BASE_DELAY_MS for a longer base backoff on overloaded (529) requests. The 2.1.301 variable sits at the other end, for the case where waiting longer gets you nothing.

Telemetry is following a similar path. On October 14 we covered 2.1.300 splitting cache writes by lifetime in OpenTelemetry events, and the same day we reported that Anthropic had opened OpenTelemetry export for the Messages API and Managed Agents in public beta. In 2.1.301 the claude-api skill gets tracing guidance, including how to set up trace destinations with the ant CLI, alongside the tool_decision fields above.

For scale, the Claudeupdates changelog tracker counts 51 changes in v2.1.301 and lists 421+ releases from v0.2.21 beta onward.

We think the model-switch summary is the worst bug fixed here. The wait-limit variable protects you from a stalled job. The summary bug spent usage credits without asking, during a model switch you would reasonably expect to cost nothing.

What we don't know

The notes don't say how far away counts as "too far" when the new variable is unset, or whether a request ended at a usage limit looks any different to your tooling from one that ran out of other retries. According to the GitHub issue, the watchdog was undocumented when the issue was filed. The release doesn't say whether the docs now cover it or the new variable.

Helmcode's 6-hour cap and 30-second heartbeat come from an outside reading and have not been confirmed against this version. Nor does anything in the inputs say whether that cap still applies once the new wait limit is set.