Claude Code Restricted Mode: What It Blocks and What It Does Not

Claude Code 2.1.248 added a --restricted flag and the equivalent CLAUDE_CODE_RESTRICTED=1 environment variable. Anthropic’s 2.1.248 release note says the mode removes built-in tools that run commands or code and removes WebFetch unless those tools are explicitly named with --tools. It also confines file tools to working directories, refuses bypassPermissions, and ignores user, project, and local settings files.

That is useful, but the name is easy to overread. Restricted mode changes the tools Claude Code exposes and the settings it loads. It does not place Claude Code in a virtual machine, container, or whole-process network sandbox. Anthropic’s sandbox comparison treats permission controls, a per-command Bash sandbox, a whole-process sandbox runtime, containers, and VMs as different layers.

The practical result

Start with this decision table.

Question	Claude Code 2.1.248 restricted mode
Can Claude call Bash, PowerShell, a REPL, or another built-in code runner by default?	No. Those tools are removed from the tool list.
Can Claude use WebFetch by default?	No. It is removed from the tool list.
Can the operator add either capability back?	Yes. Naming Bash or WebFetch with --tools makes that tool available again. Normal permission rules still decide whether a call runs.
Can Claude read and change files?	Yes. File tools remain, confined to the working directory and any path added with --add-dir. Writes still follow the permission system.
Does --dangerously-skip-permissions override the restriction?	No. Version 2.1.248 exits with bypassPermissions not supported in restricted mode.
Are repository and user settings loaded?	User, project, and local settings files are ignored. Managed policy and explicit --settings input can still apply.
Are MCP servers automatically gone?	Do not assume that. The 2.1.248 help text says to add --strict-mcp-config when you also want to skip configured MCP servers.
Is all network traffic blocked?	No. Model/API traffic is required, WebSearch can remain, explicitly enabled tools can reach the network, and optional messaging or managed integrations may communicate externally.
Is this host isolation?	No. There is no separate kernel, container boundary, or VM boundary.

The distinction matches Anthropic’s permissions documentation: permissions determine whether a tool call is allowed or prompts; isolation determines what a running process can reach.

Reproduce the 2.1.248 behavior without changing your normal install

Use a temporary package and scratch directory. This keeps the test separate from your repository and avoids replacing your normal claude executable.

mkdir -p /tmp/claude-2.1.248-proof/tool
mkdir -p /tmp/claude-2.1.248-proof/work
npm install --prefix /tmp/claude-2.1.248-proof/tool \
  @anthropic-ai/claude-code@2.1.248
printf 'restricted-mode-marker\n' > /tmp/claude-2.1.248-proof/work/marker.txt

/tmp/claude-2.1.248-proof/tool/node_modules/.bin/claude --version

The expected version line is:

2.1.248 (Claude Code)

Run from the scratch workspace and exclude previously configured MCP servers:

cd /tmp/claude-2.1.248-proof/work
../tool/node_modules/.bin/claude --restricted --strict-mcp-config

Ask for a bounded check:

Read marker.txt. Then tell me whether you have a command-running tool and whether you have WebFetch. Do not edit anything, do not use WebSearch, and do not contact any external service.

The important evidence is not whether the model uses reassuring wording. Ask What tools do you have access to?, inspect the transcript, and confirm that no Bash, PowerShell, REPL, code runner, or WebFetch call appears. The file read should still work because Read remains inside the workspace.

Prove the opt-in edge

Start a new restricted session with only WebFetch selected from the built-in tool set:

../tool/node_modules/.bin/claude \
  --restricted \
  --strict-mcp-config \
  --tools WebFetch

Now WebFetch is visible again. In Manual mode, fetching a non-preapproved domain still requires approval unless an applicable rule already allows it; Anthropic documents that distinction in the WebFetch tool behavior. Exit without approving a fetch if your goal is only to confirm availability.

Repeat with --tools Bash if you need to test the command edge. Use a harmless command such as pwd, approve it once, and then exit. The result demonstrates the exact boundary: restricted mode removes the command tool by default, but the launcher can deliberately add it back.

Do not combine this test with --allowedTools Bash, a broad allow rule, or real credentials. Tool availability and automatic approval are separate controls.

Prove that bypass mode is rejected

../tool/node_modules/.bin/claude \
  --restricted \
  --dangerously-skip-permissions \
  --strict-mcp-config

Version 2.1.248 should stop before the session starts:

Error: bypassPermissions not supported in restricted mode

When finished, exit Claude Code and remove /tmp/claude-2.1.248-proof. The test does not edit your normal Claude Code installation or project. Review the temporary directory before deleting it if you need to retain logs for an audit.

What our tool-schema test found

Superbash tested the npm package @anthropic-ai/claude-code@2.1.248 on Linux on August 28, 2026. We pointed ANTHROPIC_BASE_URL at a local HTTP capture server, supplied a fake test key, and made the server record only the tool names from the outgoing Messages request before returning a planned HTTP 400. No prompt reached Anthropic, no command ran, and no website was fetched.

Launch	Tool-schema evidence
--restricted --strict-mcp-config	The request included file and coordination tools such as Read, Glob, Grep, Edit, Write, NotebookEdit, Agent, Skill, WebSearch, ListAgents, and SendMessage. It did not include Bash or WebFetch.
Same flags plus --tools WebFetch	The selected built-in tool list contained WebFetch.
Same flags plus --tools Bash	The selected built-in tool list contained Bash.
Same flags plus --dangerously-skip-permissions	The CLI stopped with bypassPermissions not supported in restricted mode before sending a task request.

The exact remaining list can vary with platform, plan, managed policy, provider, and product features. The stable 2.1.248 claim is narrower: command/code runners and WebFetch are removed unless explicitly selected; file tools remain workspace-scoped; bypass mode is refused. That matches Anthropic’s release note and the flag description printed by the tested binary.

Remaining permissions matter

Restricted does not mean read-only. The remaining file tools can inspect and, with the applicable approval, modify files inside the workspace. A workspace containing production secrets, SSH material, cloud credentials, browser profiles, or unrelated repositories therefore gives the session more exposure than an empty scratch directory.

The working-directory boundary also expands when you pass --add-dir. Treat every added directory as an explicit data grant. Start Claude Code at the narrowest repository subdirectory that still supports the task, then check which tests and configuration files actually need access.

Restricted mode also ignores ordinary user, project, and local settings, but managed settings and a file or JSON object supplied through --settings can still apply. Launch scripts should show those arguments rather than hiding them in an alias. Use --strict-mcp-config when the test should have no previously configured MCP servers; MCP tools are separate from the built-in tool list.

WebFetch is not the whole network story

Removing WebFetch closes one direct page-retrieval path. It does not create default-deny egress.

Our restricted request still exposed WebSearch. Anthropic’s tools reference says WebSearch runs against Anthropic’s search backend and returns result titles and URLs. It does not fetch result pages itself, but it is still an external information channel.

Claude Code must also send prompts and any file content selected for context to Anthropic or the configured model provider. Anthropic’s isolation guide explicitly notes that sandboxing does not change what is sent to the model. Depending on the session and account, tools such as messaging, notifications, cloud sessions, browser integration, or MCP servers can introduce other network paths.

For a strong network boundary, enforce egress outside the model’s judgment and outside Claude Code’s tool picker:

• allow only the model/API endpoint and any reviewed package or source domains;
• block metadata endpoints, internal control planes, and private network ranges;
• use short-lived, narrowly scoped credentials inside the isolated environment;
• keep production cloud, Git, browser, and SSH credentials outside it;
• log DNS and outbound connections so a test has evidence;
• run a shutdown test that proves the environment stops and credentials expire.

The isolation recommendation

For a trusted repository on your own machine, restricted mode is a useful defense-in-depth option when you want file analysis or reviewed edits without shell execution or direct page fetches.

For an untrusted repository, external web content, autonomous work, malware analysis, or sensitive credentials, run the whole Claude Code process inside a disposable VM, microVM, or tightly configured container. Give it only the project copy it needs, use a default-deny egress policy with an explicit allowlist, and inject no production credentials. Anthropic recommends a dedicated VM or Claude Code on the web for untrusted repositories in its sandbox environment guide.

A whole-process sandbox runtime can also constrain built-in tools, hooks, and MCP servers, unlike the per-command Bash sandbox. Anthropic labels its current sandbox runtime a beta research preview, so high-assurance work should prefer the isolation technology your team already audits and operates.

Before treating an environment as disposable, prove all four exits:

1. Stop the session and confirm no Claude, MCP, hook, browser, or child process remains.
2. Revoke or expire the test token and confirm it no longer authenticates.
3. Inspect the workspace diff and outbound-connection log.
4. Destroy the container or VM, then confirm its writable layer and temporary credentials are gone.

Restricted mode is a smaller tool box. Isolation is the locked room around it. Use both when the threat model calls for both.

Sources

• Claude Code changelog: version 2.1.248
• Claude Code CLI reference
• Claude Code permissions
• Claude Code tools reference
• Claude Code security
• Choose a sandbox environment

Put this to work

Separate tool availability, permission prompts, filesystem scope, network policy, and operating-system isolation instead of calling every reduced-permission mode a sandbox.

Try

Run the reversible scratch-directory test below with Claude Code 2.1.248 and compare the default restricted tool list with explicit WebFetch and Bash opt-ins.

Prove it worked

Keep the version, launch flags, captured tool names, refusal message, and cleanup result with your security review.

Where it can pay

A documented restricted-agent runbook can become part of a safer code-review or vendor-evaluation service.

Keep in view

• Claude Code 2.1.248 removes command-running tools and WebFetch from restricted sessions unless you explicitly add them back with --tools.
• Read, search, edit, write, WebSearch, agent, messaging, and other non-command tools can remain available.
• Restricted mode limits capabilities inside Claude Code but does not isolate the process, credentials, model traffic, or every network path.
• Use --strict-mcp-config when you do not want configured MCP servers loaded into the test.

Learn the workflow: the supervised Claude Code workflow →