--restricted strips code execution from Claude Code 2.1.248

On August 27 Anthropic added a locked-down launch mode to Claude Code. If you start a session with --restricted, the agent loses every built-in tool that runs commands or code, and it loses WebFetch too. File access stays inside the working directory, and your user, project and local settings files are not read.
The flag is the first item in the version 2.1.248 release notes on GitHub. The same release fixes two separate prompt-cache misses, and most of what’s left is fixes to agent view, background sessions and the login flow.
What --restricted takes away
You can turn the mode on with the flag or with the environment variable CLAUDE_CODE_RESTRICTED=1. Once it’s on, four things change.
- Built-in tools that execute commands or code are removed, and so is WebFetch. A tool you name explicitly in
--toolsstays available. - File tools still work, but only inside the working directory.
- The session refuses
bypassPermissions. - User, project and local settings files are ignored.
This works differently from the permission modes Claude Code already has. Anthropic’s permission-mode documentation describes dontAsk as the mode for locked-down CI and scripts. In that mode, file reads inside working directories and pre-approved tools run, and anything that would normally prompt is denied. Under --restricted, the command-running tools aren’t in the session at all unless you list them. The same docs say bypassPermissions runs everything without asking and is meant only for isolated containers and VMs. A restricted session refuses that mode.
Ignoring settings files matters most when the code you’re looking at belongs to someone else. Claude Code reads settings from up to five places. From highest priority to lowest they are managed settings, the command line (--settings), local project (.claude/settings.local.json), shared project (.claude/settings.json) and user (~/.claude/settings.json). The shared project file ships inside the repository. A restricted session skips it, along with the local file next to it and your own user file, so a cloned repo can’t bring its own permission rules or configuration into the session.
The mode looks built for reading and editing code you don’t trust yet, with the agent unable to run anything in it. Any tool you need back has to be named in --tools.
Cache misses and token weight
The first cache fix covers a miss that happened roughly once an hour in long sessions, and the session lost its extended-thinking context along with it. The cause was tool definitions being re-rendered after an OAuth token refresh.
The second involved --resume. If the account had gone into usage overage, the ScheduleWakeup tool definition changed between the original session and the resumed one. The resumed session’s first turn then missed the cache completely.
Agents also get their own cache setting. experimental.cacheTtl in agent frontmatter takes "5m" or "1h" and sets a per-agent prompt cache TTL, which is how long that agent’s cached prompt stays valid. It applies only when no subagent TTL setting is configured. That setting, subagentPromptCacheTtl, arrived a few releases earlier alongside promptCacheTtl, so the main conversation could hold a 1-hour cache while subagents stayed at 5 minutes. The new field sets the TTL one agent at a time.
The Workflow tool’s description is now about 1k tokens instead of 5.7k. The script-writing reference has moved out of it into a bundled workflow-authoring skill.
Agent view and background sessions
If the machine had been switched off, agent view could bring back a background session that was weeks old. Such a session now shows as stopped at the time it actually ended, and opening it asks before resuming the saved conversation. Starting a new session no longer sometimes opens an older conversation and throws away the prompt you typed. And opening a stopped session that is already resumed in another terminal no longer starts a second process on the same conversation. The row now says the session is open in a terminal.
A background worktree session now holds the worktree’s lock while it runs, so cleanup and git worktree remove leave its checkout alone. In the other direction, claude agents and claude rm had refused to delete a session with the message “has commits that are not pushed anywhere” when its branch was already merged into your checked-out default branch but not yet pushed. That’s fixed.
Hooks used to fail silently in two cases. If a PermissionRequest or PreToolUse hook printed an invalid answer, a background session just waited. The agents row now names the hook and the schema error. If a hook printed a {…} object on stdout that wasn’t valid JSON, it was treated as plain text. It’s now reported as a hook error with the parse message.
claude agents had been skipping the workspace trust prompt whenever the CI environment variable was set, and it crashed at launch if the PR-status cache held a malformed entry. Both are fixed. In the dispatch input, shift+enter now inserts a newline, as it does in the prompt, and ctrl+enter dispatches and attaches.
Cross-session messaging (SendMessage and ListAgents between sessions on the same machine) now also works on Bedrock, Vertex and Foundry, and with telemetry disabled. If the default directory can’t be used, it falls back to a private per-user /tmp directory, and both the notice and /status name the directory to fix. An invalid crossSessionInbound value used to be ignored without a word. Now it triggers a warning and, until the value is corrected, cross-session messages are held if it’s set in user settings and refused if it’s set in managed settings. When a subagent uses SendMessage to reach another session, the result now notes that any reply goes to the parent session’s conversation and not to the subagent.
For admins and organizations
Server-managed settings now explain their failures. You get a startup warning if they fail to load. /doctor and /status show a line explaining the load failure, or why the settings weren’t fetched at all, for example because the session runs on Bedrock, Vertex or another third-party provider, or uses a custom ANTHROPIC_BASE_URL. Client-side timeout, MCP startup-mode and stream-watchdog environment variables no longer trigger the settings-approval prompt.
Transcript cleanup had been deleting sessions written by Claude Desktop and Cowork after 30 days. Cleanup now keeps those sessions as long as they are in the app, unless org policy manages retention, and the new desktopSessionCleanupPeriodDays setting caps that exemption.
/usage-credits now reaches Enterprise organizations billed through AWS Marketplace, self-serve Enterprise and Enterprise trials, so members can ask their admin for a higher usage limit. Rate-limit, usage and fast-mode messages no longer tell you to run the command when your organization doesn’t have it, for example when DISABLE_EXTRA_USAGE_COMMAND hides it. claude self-hosted-runner accepts --client-label <label> or SELF_HOSTED_RUNNER_CLIENT_LABEL to replace the hostname it registers under by default. /loop‘s self-paced dynamic mode and its no-prompt autonomous default are now always available, including on Bedrock, Vertex and Foundry. Failures to export Anthropic’s own telemetry now log at debug level as [Anthropic telemetry], so they aren’t mistaken for your OTel collector failing.
Other changes in 2.1.248:
/web-setupwarns when the GitHub CLI token lacks theworkflowscope, since pushes to very large repositories can be rejected without it.- If another Claude Code process holds the token refresh lock while your session token has expired, the request now fails with a retryable error and no longer sends you to the login screen.
- On machines where the recommended Console sign-in in
/logincan’t be used, for example whenANTHROPIC_API_KEYis set, it falls back to API-key sign-in. - MCP servers whose
headersHelpersupplies the Authorization header now re-run the helper and retry on a 401, as documented, without falling into OAuth discovery. - Gateway model discovery now runs when
apiKeyHelperis the only credential. - Model names in
/modelrender as code, so a suffix like[1m]no longer shows up as a link. claude logsno longer leaves mouse tracking, bracketed paste and the alternate screen switched on in your terminal.- The prompt-footer PR badge checks GitHub less often while the pull request is unchanged.
- In VS Code, a chat tab stuck on “No conversation found” now starts a new conversation.
/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 if not. Before, it failed after the cloud session had already started. /ultrareview and locally seeded cloud sessions had also been uploading uncommitted edits to prod.env-style and *.tfvars files, along with editor swap, temp and backup copies of credential files such as key.pem.tmp and id_rsa.swo. Those files now stay on your machine.
Up next
Free Claude seats for 10,000 scientists, $15 premium, Video
Claude went free for 10,000 scientists through a new Team plan, with premium seats at $15 a month, an 80% discount, for one year. Anthropic says it plans to push well past that initial 10,000 in the coming months.
Related stories
- Claude Code 2.1.246 flags wildcard Bash allow rules
- Claude Code 2.1.251 streams subagent work live
- Claude Code 2.1.247 drafts its own feedback reports
- Claude Code 2.1.243 uses your contracted model rates
- Claude Code on desktop folds an iPhone Duo to test layouts
- Claude Code 2.1.318: login expiry warning, runner log change
Comments
No comments yet. Be the first.
Join the conversation
Sign in to leave a comment. It appears after moderation.

