Claude Code v2.1.248 shipped Thursday with --restricted
— a new permission mode that drops shell execution, web fetching, and project-level settings files from the agent’s toolkit. One flag, one hard guarantee, no classifier in the middle. If you run Claude Code in CI, against client repos, or on any machine you don’t fully control, update now and flip the switch.
What the Flag Actually Removes #
Restricted mode strips four capabilities from the session:
Bash and code execution— no shell commands, no script runners** WebFetch**— the agent cannot make outbound HTTP requests** bypassPermissions**— cannot be escalated mid-session, even by a user flag** Project and local settings files**— a cloned.claude/
directory or.mcp.json
is ignored entirely
That last item is the most important one. The TrustFall vulnerability class, disclosed in May, showed how a malicious repository could inject an .mcp.json
that auto-approved itself and executed arbitrary code — with CI pipelines being the worst case because there’s no human to dismiss a dialog. In restricted mode, the settings files are never read. The attack surface is gone.
What Still Works #
Restricted mode is not a lobotomy. File reads and writes still work — scoped to the current working directory. MCP tools work if you explicitly name them with --tools
. Claude’s reasoning, analysis, and structured output are fully intact. For the tasks you’d actually run unattended — code review, security analysis, generating a changelog, summarizing a diff — restricted mode loses nothing meaningful.
How to Use It #
Two options. For one-off sessions:
claude --restricted
For CI runners and wrapper scripts, the environment variable is cleaner. Set it once per runner and every invocation is restricted without touching any command:
export CLAUDE_CODE_RESTRICTED=1
In a GitHub Actions workflow:
- name: Claude Code Review
env:
CLAUDE_CODE_RESTRICTED: "1"
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: claude --print "Review this diff for security issues"
One thing worth noting: restricted mode refuses bypassPermissions
even if you explicitly pass it. There is no combination of flags that turns a restricted session back into a fully autonomous one mid-run. That is the point.
Where This Fits in the Permission Landscape #
Before restricted mode, the options for headless Claude Code use were unsatisfying. Default mode generates too many prompts for unattended operation. acceptEdits
still allows shell commands with a prompt. Auto mode uses a live classifier to evaluate each operation — solid, but not available on Pro or Max plans. And --dangerously-skip-permissions
goes the opposite direction: zero prompts, full access, appropriate only inside a fully isolated container or VM.
Restricted mode fills the gap. Pro and Max teams now have a safe headless option that doesn’t require classifier infrastructure and doesn’t hand over the shell. Here’s how it compares:
| Mode | Shell | WebFetch | Files | Project Settings |
|---|---|---|---|---|
| Default | Prompt | Prompt | Prompt | Reads |
| acceptEdits | Prompt | Prompt | Auto (cwd) | Reads |
| Auto | Classifier | Classifier | Classifier | Reads |
| bypassPermissions | Yes | Yes | All paths | Reads |
| Restricted | No | No | cwd only | Ignored |
The Broader Signal #
Restricted mode is Anthropic signaling, structurally, that Claude Code agents are expected to run unattended on machines they don’t own, in pipelines they don’t control, and against code they didn’t write. This isn’t a feature you demo — it’s production infrastructure. Teams shipping AI-assisted code review in CI, running Claude Code against customer repos, or deploying agents on shared runners now have a sane default that doesn’t require trust in the environment.
The official permission modes docs cover the full flag reference and edge cases. Check the v2.1.248 release notes for everything else in this release.