Claude Code v2.1.248 Adds --restricted to Lock Down Risky Actions!

Hey, it's me, Shiichan! Today's Claude Code release notes are packed, so let me walk you through them with extra energy!

Claude Code Release github.com

What was announced?

Claude Code's GitHub release page published the changes for v2.1.248. It's a huge batch this time, ranging from a new security-focused feature to a long list of fixes for issues that actually hurt in practice.

The story so far

By default, Claude Code could run command-execution and code-execution tools plus WebFetch, and it read user, project, and local settings files as usual. There wasn't a solid way to lock things down when working with a repository you don't fully trust, or when running Claude Code unattended in CI.

On top of that, in long sessions, tool definitions got re-rendered after every OAuth token refresh, causing a prompt-cache miss (and losing extended-thinking context) roughly once an hour.

What changes

Here's what's new:

• 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

And here are the fixes that matter most in practice:

• 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: transcript cleanup now keeps desktop-written sessions while they are in the app (unless org policy manages retention), with a new desktopSessionCleanupPeriodDays setting capping 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
• 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

Dive Deep

There's also a large batch of smaller fixes across Remote Control, claude agents, hooks, and MCP. A few highlights:

• Fixed claude agents skipping the workspace trust prompt when CI is set, and fixed it crashing on launch when the PR-status cache held a malformed entry
• 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
• Improved the Workflow tool's prompt footprint from about 5.7k tokens to about 1k, moving the script-writing reference into a bundled workflow-authoring skill
• Changed /loop: self-paced dynamic mode and the no-prompt autonomous default are now always available, including on Bedrock/Vertex/Foundry
• Changed shift+enter in the agent view dispatch input to insert a newline; ctrl+enter now dispatches and attaches

On top of that, Windows' claude agents list no longer ignores keyboard input after detaching, /login's recommended sign-in no longer fails with an OAuth error on API-key setups, and model-name suffixes like [1m] now render as code instead of turning into a link.

Wrap-up

• --restricted gives you a lockdown mode that blocks command execution and WebFetch and ignores settings files.
• Smaller additions include experimental.cacheTtl, the self-hosted-runner --client-label flag, and server-managed settings diagnostics.
• Fixes address real pain points: prompt-cache misses, disappearing Claude Desktop sessions, and unintended uploads of sensitive files.
• Plenty of smaller fixes landed across Remote Control and claude agents too.
• Especially useful if you run Claude Code in CI or on untrusted repos, or if you rely on long-running sessions every day.