Claude Code v2.1.248: --restricted Mode, Per-Agent Prompt Cache TTL, and Cross-Session Messaging on Bedrock, Vertex, and Foundry

Claude Code v2.1.248 is a large release with 49 changelog entries. It adds a --restricted mode that removes command-running tools and ignores user, project, and local settings files, a per-agent prompt cache TTL in agent frontmatter, diagnostics for server-managed settings, and cross-session messaging on Bedrock, Vertex, and Foundry. It also fixes two causes of prompt-cache misses, keeps Claude Desktop and Cowork sessions from disappearing after 30 days, and resolves many issues in claude agents, hooks, MCP, and Remote Control.

What’s New

`--restricted` Mode

The new --restricted flag (or CLAUDE_CODE_RESTRICTED=1) removes the built-in tools that run commands or code and WebFetch (unless named in --tools). It also keeps file tools inside the working directory, refuses bypassPermissions, and ignores user, project, and local settings files.

Per-Agent Prompt Cache TTL

Agent frontmatter now accepts experimental.cacheTtl ("5m" or "1h"), a per-agent prompt cache TTL that is used when no subagent TTL setting is configured.

Server-Managed Settings Diagnostics

Claude Code now shows a startup warning when server-managed settings fail to load, and /doctor and /status include a line explaining a load failure or why the settings weren’t fetched (Bedrock/Vertex/third-party provider, custom ANTHROPIC_BASE_URL).

Cross-Session Messaging on Bedrock, Vertex, and Foundry

Cross-session messaging (SendMessage / ListAgents) between sessions on the same machine now works on Bedrock, Vertex, and Foundry, and when telemetry is disabled.

Self-Hosted Runner Client Label

claude self-hosted-runner --client-label <label> (or SELF_HOSTED_RUNNER_CLIENT_LABEL) overrides the label the runner registers with; the default is the hostname.

`/usage-credits` for More Enterprise Organizations

/usage-credits is now available for Enterprise organizations billed through AWS Marketplace, self-serve Enterprise, and Enterprise trials, so members can request a higher usage limit from their admin.

Smaller Workflow Tool Footprint

The Workflow tool’s description is now about 1k tokens instead of 5.7k, with the script-writing reference moved into a bundled workflow-authoring skill.

Agent View and `/loop` Changes

In the agent view dispatch input, shift+enter now inserts a newline (matching the prompt), and ctrl+enter dispatches and attaches. /loop’s self-paced dynamic mode and no-prompt autonomous default are now always available, including on Bedrock/Vertex/Foundry.

Fixes and Improvements

Prompt cache: 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, is fixed. The ScheduleWakeup tool definition no longer changes between a session and its --resume when the account had entered usage overage, which had caused a full prompt-cache miss on the resumed session’s first turn.
Desktop session retention: Claude Desktop and Cowork sessions no longer disappear after 30 days. Transcript cleanup now keeps desktop-written sessions while they are in the app (unless org policy manages retention), and the new desktopSessionCleanupPeriodDays setting caps the exemption.
Local files in cloud uploads: /ultrareview and locally seeded cloud sessions no longer upload 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.
Sign-in: You are no longer sent to the login screen when another Claude Code process held the token refresh lock while the session token had expired; the request now fails with a retryable error instead. The recommended Console sign-in in /login no longer fails with an OAuth error on machines where it can’t be used (for example when ANTHROPIC_API_KEY or an API key helper is set); it now falls back to the API-key sign-in.
claude agents: claude agents no longer skips the workspace trust prompt when the CI environment variable is set, and no longer crashes on launch when the PR-status cache held a malformed entry. Agent view no longer resurrects a weeks-old background session after the machine was off; such a session now shows as stopped at its real end, and opening it asks before resuming its saved conversation.
Worktrees: A backgrounded worktree session no longer loses its checkout, because the background session now holds the worktree’s lock while it runs, so cleanup and git worktree remove leave it alone. claude agents and claude rm no longer refuse to delete a session (“has commits that are not pushed anywhere”) when its worktree branch was already merged into your checked-out default branch but not yet pushed.
Hooks: Background sessions no longer wait silently when a PermissionRequest or PreToolUse hook prints an invalid answer; the claude agents row now names the hook and the schema error. A stdout {…} object that isn’t valid JSON is now reported as a hook error with the parse message instead of being treated as plain text.
MCP and gateways: MCP servers whose headersHelper supplies the Authorization header now re-run the helper and retry the call on a 401, as documented, instead of falling into OAuth discovery. /login to a Claude apps gateway no longer hangs when the managed-settings security approval dialog is required.
Remote Control and cloud sessions: Remote Control sessions no longer occasionally fail to show a permission prompt or the latest messages on the connected device after the CLI silently reconnects. Cloud sessions no longer occasionally fail at startup when the container’s session credentials are not yet readable.
Cross-session messaging: An invalid crossSessionInbound value is no longer silently ignored; it now warns and holds cross-session messages (user settings) or refuses them (managed settings) until fixed.
GitHub: /web-setup now warns when the GitHub CLI token lacks the workflow scope, since pushes to very large repositories can be rejected without it. /ultrareview <PR#> now checks before launch that the GitHub account connected to your Claude account can access the repository, and explains how to fix it, instead of failing after the cloud session starts.

This release contains 49 changes in total; see the official changelog linked below for the complete list.

How to Update

Check your installed version: claude --version
Update in place: claude update
In the agent view dispatch input, shift+enter now inserts a newline; use ctrl+enter to dispatch and attach.