Claude Code Restricted Mode: Lock Down Your CI Agent

Anthropic shipped Claude Code v2.1.248 on Thursday with a new `--restricted` permission mode that disables shell execution, web fetching, and project-level settings files, addressing the TrustFall vulnerability class disclosed in May that allowed malicious repositories to execute arbitrary code via `.mcp.json` files. The mode, which also blocks `bypassPermissions` escalation, is designed for CI pipelines and unattended use, and is available to Pro and Max plan users.

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 https://adversa.ai/blog/trustfall-coding-agent-security-flaw-rce-claude-cursor-gemini-cli-copilot/ , 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 https://www.microsoft.com/en-us/security/blog/2026/06/05/securing-ci-cd-in-an-agentic-world-claude-code-github-action-case/ 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 https://code.claude.com/docs/en/permission-modes cover the full flag reference and edge cases. Check the v2.1.248 release notes https://github.com/anthropics/claude-code/releases/tag/v2.1.248 for everything else in this release.