# Claude Code v2.1.248

- Product: Claude Code (https://whatsnew.fyi/product/claude-code)
- Vendor: Anthropic
- Date: 2026-08-27
- Version: v2.1.248
- Original notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.248
- Permalink: https://whatsnew.fyi/product/claude-code/releases/v2.1.248

What's New is an index, not a publisher: every entry below links to the vendor's own release notes, which are the authoritative source. Entries are labelled where they are hand-curated sample data, pre-releases, or drawn from a secondary source such as a developer blog.

Reuse: the summaries, labels and curation here are © What's New. Quote freely with attribution and a link back; wholesale republication of the corpus is not permitted — terms: https://whatsnew.fyi/terms. The vendors' own release notes remain their publishers'.

---

- **added** — Add --restricted flag to remove built-in tools that run commands or code and WebFetch, keep file tools inside the working directory, refuse bypassPermissions, and ignore user, project and local settings files
- **added** — Add experimental.cacheTtl to agent frontmatter to configure per-agent prompt cache TTL
- **added** — Add claude self-hosted-runner --client-label option to override the label the runner registers with
- **added** — Add server-managed settings diagnostics with startup warnings and /doctor and /status endpoints
- **added** — Add warning in /web-setup when the GitHub CLI token lacks the workflow scope
- **added** — Add /usage-credits for Enterprise organizations to request higher usage limits
- **added** — Add cross-session messaging between sessions on the same machine on Bedrock, Vertex, and Foundry
- **fixed** — Fix prompt-cache miss caused by tool definitions being re-rendered after an OAuth token refresh
- **fixed** — Fix ScheduleWakeup tool definition changing between a session and its --resume when account had entered usage overage
- **fixed** — Fix Claude Desktop and Cowork sessions disappearing after 30 days by keeping desktop-written sessions while they are in the app
- **fixed** — Fix being sent to the login screen when another Claude Code process held the token refresh lock; the request now fails with a retryable error instead
- **fixed** — Fix the claude agents list not responding to the keyboard on Windows after detaching from a session
- **fixed** — Fix recommended Console sign-in in /login failing with an OAuth error on machines where it cannot be used by falling back to API-key sign-in
- **fixed** — Fix model names in /model to render as code so suffixes display literally
- **fixed** — Fix claude agents skipping the workspace trust prompt when the CI environment variable is set
- **fixed** — Fix claude agents crashing on launch when the PR-status cache held a malformed entry
- **fixed** — Fix agent view opening a stopped session that was already resumed in another terminal by no longer starting a second process
- **fixed** — Fix claude agents and claude rm refusing to delete a session when its worktree branch was already merged into the default branch
- **fixed** — Fix /login to a Claude apps gateway hanging when the managed-settings security approval dialog was required

##### What's changed

- Added `--restricted` (or `CLAUDE_CODE_RESTRICTED=1`): removes the built-in tools that run commands or code and `WebFetch` (unless named in `--tools`), keeps file tools inside the working directory, refuses `bypassPermissions`, and ignores user, project and local settings files
- Added `experimental.cacheTtl` (`"5m"` or `"1h"`) to agent frontmatter: a per-agent prompt cache TTL used when no subagent TTL setting is configured
- Added `claude self-hosted-runner --client-label <label>` (or `SELF_HOSTED_RUNNER_CLIENT_LABEL`) to override the label the runner registers with (default: hostname)
- Added server-managed settings diagnostics: a startup warning when the settings fail to load, and a `/doctor` and `/status` line explaining a load failure or why they weren't fetched (Bedrock/Vertex/third-party provider, custom `ANTHROPIC_BASE_URL`)
- Added a warning in `/web-setup` when the GitHub CLI token lacks the `workflow` scope, since pushes to very large repositories can be rejected without it
- Added `/usage-credits` for Enterprise organizations billed through AWS Marketplace, self-serve Enterprise, and Enterprise trials, so members can request a higher usage limit from their admin
- Added cross-session messaging (`SendMessage` / `ListAgents`) between sessions on the same machine on Bedrock, Vertex, and Foundry, and when telemetry is disabled
- 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
- Fixed the `ScheduleWakeup` tool definition changing between a session and its `--resume` when the account had entered usage overage, causing a full prompt-cache miss on the resumed session's first turn
- Fixed Claude Desktop and Cowork sessions disappearing after 30 days: the transcript cleanup now keeps desktop-written sessions while they are in the app (unless org policy manages retention); the new `desktopSessionCleanupPeriodDays` setting caps the exemption
- Fixed being 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
- Windows: Fixed the `claude agents` list not responding to the keyboard after detaching from a session, or when launched in a terminal tab left in win32-input-mode
- Fixed the recommended Console sign-in in `/login` failing with an OAuth error before showing a sign-in URL 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
- Fixed model names in `/model` and fast-mode switch notices to render as code, so suffixes like `[1m]` display literally instead of as a link
- Fixed `claude agents` skipping the workspace trust prompt when the `CI` environment variable is set
- Fixed `claude agents` crashing on launch when the PR-status cache held a malformed entry
- Fixed agent view resurrecting 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
- Fixed agent view sometimes opening an older conversation, and dropping the typed prompt, when starting a new session
- Fixed `claude agents`: opening a stopped session that you already resumed in another terminal no longer starts a second process on that conversation; the row now says it is open in a terminal
- Fixed `claude agents` and `claude rm` refusing to delete a session ("has commits that are not pushed anywhere") when its worktree branch was already merged into your checked-out default branch (e.g. local `main`) but not yet pushed
- Fixed background sessions waiting silently when a `PermissionRequest` or `PreToolUse` hook prints an invalid answer: the `claude agents` row now names the hook and the schema error
- Fixed hooks silently treating a stdout `{…}` object that isn't valid JSON as plain text; it's no

_[Truncated at 4000 characters — full notes: https://github.com/anthropics/claude-code/releases/tag/v2.1.248]_