Claude Code 2.1.248: a restricted mode lands, and your long sessions were losing their cache every hour

Two releases since the last digest: 2.1.248 on August 27 and 2.1.250 on August 28. There is no 2.1.249, it was skipped. And 2.1.250 amounts to "Bug fixes and reliability improvements", the third silent release this month. Everything is in 2.1.248, and there is a lot of it.

The through line is never stated, but it is obvious once you line the entries up: this release tightens the perimeter. What Claude Code is allowed to execute, what it is allowed to read, and what is allowed to leave your machine. Underneath, a quieter and more immediately profitable thread: three prompt cache fixes. Here is the triage.

--restricted: a Claude Code that runs nothing and ignores your settings

This is the release's headline addition, and it opens a whole category of use. The new --restricted flag, or CLAUDE_CODE_RESTRICTED=1, starts a deliberately amputated session:

• the built-in tools that run commands or code are removed, along with WebFetch;
• file tools stay confined to the working directories;
• bypassPermissions is refused, including its --dangerously-skip-permissions alias;
• user, project and local settings files are not loaded at all.

The flag's documentation adds three things the changelog leaves out, and each one matters.

First, the intended use. The docs do not describe a general-purpose safe mode. They say it plainly: use it "when an evaluation harness drives claude on a shared machine and Claude Code must not run commands or read that machine's user and project settings". This is configuration containment, not a sandbox. If your problem is running hostile code safely, the answer is still sandboxing, not this flag.

Second, the --tools catch. You can get the removed tools back, but only by naming them individually in --tools. The default preset will not bring them back. So --restricted --tools default reopens nothing, which is not what a quick read suggests.

Third, the exact settings scope. The changelog says it "ignores user, project and local settings files". The docs state the same rule positively, which is more useful: the session loads only managed settings and whatever you pass through --settings. Your administrator keeps control, and you start from a clean, explicit baseline.

One last thing if you script this: the flag requires 2.1.248 or later. On an older build it is not politely ignored, it simply does not exist.

Your prompt cache was dropping once an hour

The most profitable fix in the release is one line among fifty, and you have to unpack it to see what it was costing:

Fixed a prompt-cache miss (and lost extended-thinking context) roughly once an hour in long sessions, caused by tool definitions being re-rendered after an OAuth token refresh.

The mechanism is unpleasant. The prompt cache works on prefix matching: as long as the start of your request is byte-for-byte identical to the previous turn's, you do not pay to reprocess it. Tool definitions sit right at the front of that prefix. An OAuth token refresh caused them to be re-rendered, the prefix changed, and the entire cache went with it. Since tokens refresh on a regular cadence, this happened roughly hourly, on exactly the sessions that are most expensive to rebuild: the long ones. Losing extended-thinking context along the way is the second bill, and that one never shows up on an invoice.

Its immediate cousin is a second cache fix: the ScheduleWakeup tool definition changed between a session and its --resume once the account had entered usage overage, which cost a full cache miss on the resumed session's first turn. Same mechanic, same root cause, an unstable tool definition.

The third entry in the thread is pure context savings: the Workflow tool's prompt footprint drops from about 5,700 tokens to about 1,000, with the script-writing reference moved into a bundled workflow-authoring skill that loads on demand. Same logic as tool search for MCP servers: put only what is used in the prompt, defer the rest. Roughly 4,700 tokens handed back to every session for free.

While we are on caching, the release adds experimental.cacheTtl ("5m" or "1h") to agent frontmatter: a per-agent prompt cache lifetime, used when no subagent TTL setting is configured. It follows directly from what we covered in the 2.1.243 to 2.1.245 digest: promptCacheTtl covers the main conversation, subagentPromptCacheTtl covers everything else, and here is the finer notch, agent by agent.

Two cautions before you reach for it. The experimental. prefix is not decoration: the field is absent from the frontmatter table in the subagents documentation, which lists name, description, tools, model, permissionMode, maxTurns and the rest without it. Undocumented means it can be renamed or dropped. And the one-hour cache is not free: cache writes are billed at a higher rate, so an agent that works in short bursts pays the write premium without ever benefiting from the lifetime. The right candidate is the agent you come back to after a long pause.

Three families of secret files that were riding into the cloud

The security fix of the release, and it deserves a stop, because it covers files nobody thinks to watch:

Fixed /ultrareview and locally seeded cloud sessions uploading uncommitted edits to prod.env-style and *.tfvars files, or to editor swap, temp, and backup copies of credential files (e.g. key.pem.tmp, id_rsa.swo); they now stay on your machine.

You need the seeding mechanism to gauge the scope. The ultrareview docs are explicit: for a branch review, "Claude Code bundles the repository state and uploads it to a remote sandbox", while for a pull request review, "Claude Code uploads nothing from your machine". The bundle includes uncommitted changes, which is exactly the point of a branch review: it sees your work in progress.

So a filter already existed, but it missed three categories. Environment files whose name does not match the expected pattern, prod.env rather than .env. Terraform *.tfvars, which routinely carry infrastructure credentials. And above all the editor artifacts: key.pem.tmp, id_rsa.swo. Those are the nastiest, because they appear on their own the moment you open a key in vim, carry a name your .gitignore almost certainly does not cover, and survive an editor crash without you ever knowing.

Nothing to configure, the fix is in the client. But take two habits from it. If you have run branch reviews on a repository holding files like these, treat those secrets as having left your machine, with whatever internal policy that implies. And going forward, remember that PR review uploads nothing: when the directory holds sensitive material, push the branch and pass the PR number.

Still on credentials, the same release stops rendering them onto the wrong surface: model names in /model and in fast-mode switch notices are now rendered as code, so a suffix like [1m] displays literally instead of being turned into a link.

claude agents stops eating your worktrees and your sessions

A cluster of fixes on agent view and background sessions, three of which were destroying or losing something.

The worktree pulled out from under a session. A backgrounded session was losing its checkout. It now holds the worktree's lock while it runs, so cleanup and git worktree remove leave it alone. That is two digests in a row where an automatic sweep deleted a worktree that was in use.

The three-week-old zombie session. Agent view was resurrecting a background session from weeks earlier after the machine had been off. It now shows as stopped at its real end, and opening it asks before resuming the saved conversation. In the same vein, opening a stopped session you already resumed in another terminal no longer starts a second process on that conversation; the row says it is open elsewhere.

The refusal to delete an already-merged branch. claude agents and claude rm refused to delete a session with "has commits that are not pushed anywhere" when its worktree branch was already merged into your local default branch, just not pushed yet. The guardrail was right in intent and wrong in measurement.

Two diagnostic fixes round out the cluster, both aimed at the same blind spot: a hook that answers nonsense. A background session waited silently when a PermissionRequest or PreToolUse hook printed an invalid answer; the row now names the hook and the schema error. And a stdout {…} object that is not valid JSON is no longer silently treated as plain text, it surfaces as a hook error with the parse message. If you write hooks, these two will save you an evening.

Cross-session messaging arrives on Bedrock, Vertex and Foundry

Cross-session messaging (SendMessage and ListAgents) now works between sessions on the same machine on Amazon Bedrock, Google Vertex and Microsoft Foundry, and in sessions with telemetry disabled. That is a real unblock: the feature depended on feature-flag evaluation, so any variable that cut non-essential traffic switched it off as a side effect.

One warning if you go check the docs: as of writing, the Availability section still lists those same platforms as unsupported, and still says DISABLE_TELEMETRY or DO_NOT_TRACK are enough to turn messaging off. The page has not caught up with a changelog entry dated yesterday. Trust /list-agents in your own session over the page.

Three adjustments come with the opening. An invalid crossSessionInbound value is no longer silently ignored: it warns and holds messages when it comes from user settings, or refuses them when it comes from managed settings. The mechanism falls back to a private per-user /tmp directory when the default one cannot be used, and both the notice and /status name the directory to fix. And in Linux user namespaces, root-equivalent trust for unmapped owners is now limited to canonical system directories: a quiet piece of hardening, but exactly the kind of shortcut that turns into a privilege escalation inside a container.

Last item in the same family: a SendMessage sent from a subagent to another session now notes in its result that any reply lands in the parent session's conversation, not with the subagent. An ergonomic detail for a human, an important correction for an agent that would otherwise wait forever for an answer arriving somewhere else.

The rest, briefly

• Your Desktop and Cowork sessions no longer vanish after 30 days. Transcript cleanup now keeps desktop-written sessions while they are in the app, unless an org policy manages retention. The new desktopSessionCleanupPeriodDays setting caps that exemption.
• /loop dynamic mode and the no-prompt autonomous default are now always available, including on Bedrock, Vertex and Foundry.
• /usage-credits arrives for Enterprise organizations billed through AWS Marketplace, self-serve Enterprise, and Enterprise trials, so members can ask their admin for a higher limit. Symmetrically, rate-limit and fast-mode messages stop pointing you at that command when it does not exist for your org, for instance under DISABLE_EXTRA_USAGE_COMMAND.
• /web-setup warns when your GitHub CLI token lacks the workflow scope, since pushes to very large repositories can be rejected without it. In the same area, /ultrareview <PR#> now checks before launch that the GitHub account connected to your Claude account can reach the repository, and explains how to fix it, instead of failing after the cloud session has started.
• Server-managed settings diagnostics: a startup warning when they fail to load, and a /doctor and /status line explaining the failure or why they were not fetched (third-party provider, custom ANTHROPIC_BASE_URL).
• Login: you are no longer bounced to the login screen when another Claude Code process holds the token refresh lock while your session token has expired; the request fails with a retryable error instead. And the recommended Console sign-in in /login, which failed with an OAuth error before showing any URL on machines where it cannot be used (ANTHROPIC_API_KEY set, an API key helper configured), now falls back to API-key sign-in.
• Windows and terminals: the claude agents list stopped responding to the keyboard after detaching from a session, or in a tab left in win32-input-mode. claude logs left mouse tracking, bracketed paste and the alternate screen switched on in the terminal it ran from. Startup warnings rendered one column to the right of everything else. And the trust dialog showed a garbled character when a long rule was cut mid-emoji.
• Ergonomics: shift+enter in the agent view dispatch input now inserts a newline like it does in the prompt, and ctrl+enter dispatches and attaches. The permission mode indicator no longer hides behind the "Press Ctrl-C again to exit" hint when you hit shift+tab right after ctrl+c. And @-mentions of other sessions finally match names typed in non-Latin characters, Korean entered through an IME for example.
• MCP and gateways: an MCP server whose headersHelper supplies the Authorization header fell into OAuth discovery on a 401 instead of re-running the helper and retrying, as the docs promise. /mcp listed a project .mcp.json entry declaring the claude.ai connector type under the trusted "claude.ai" heading; it now appears under its real scope. Gateway model discovery never ran when apiKeyHelper was the only credential. And /login to a Claude apps gateway hung when the managed-settings security approval dialog was required.
• Miscellaneous: cloud sessions occasionally failed at startup when the container's credentials were not yet readable. Remote Control sessions sometimes never showed a permission prompt or the latest messages after a silent reconnect. claude remote-control rejected its own flags when a global flag preceded the subcommand. Anthropic telemetry export failures now log as [Anthropic telemetry] rather than [3P telemetry] OTEL diag error, so they are not mistaken for your own collector failing. The prompt-footer PR badge checks GitHub less often while the PR is unchanged. Client timeout, MCP startup-mode and stream-watchdog env vars no longer trigger the settings-approval prompt. And in VS Code, a chat tab stuck on "No conversation found" now starts a new conversation.

What to take away

Take the release, and decide one thing today: if you use /code-review ultra in branch mode on repositories that hold environment files or keys, update before your next review, and spend ten minutes working out what may already have left. The rest of the time, PR review is the mode that uploads nothing.

For everyone else, 2.1.248 hands back context and money without asking for anything: a cache that no longer collapses every hour, and 4,700 tokens of tool description that no longer move into every session. It is rare for an update to pay for itself this mechanically.

And if you automate Claude Code on a shared machine, go read --restricted. It is the first flag in the client that gives you a session whose configuration you actually know, because it only reads yours.