Claude Code Restricted Mode: Lock Down Your CI Agent

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.