Originally published on IndieSeek.
Claude Code 2.1.248 restricted mode: shrink local authority without calling it a sandbox
Quick answer
Claude Code 2.1.248, released on August 27, 2026, adds --restricted and the equivalent environment variable CLAUDE_CODE_RESTRICTED=1. The mode removes built-in command and code execution tools plus WebFetch unless you explicitly name them with --tools. It also ignores user, project, and local settings, confines file tools to the working directories, and refuses bypassPermissions.
That is a useful low-authority starting point for reviewing an unfamiliar repository or running a narrow CI task. It is not an operating-system sandbox. Managed settings and an explicit --settings input still apply; --add-dir expands the file boundary; configured MCP servers need a separate --strict-mcp-config decision; and any tool you deliberately restore carries its own authority. Treat restricted mode as a safer CLI composition, then verify the effective tool, file, settings, and MCP surfaces before relying on it.
Who this is for
This guide is for developers who want Claude Code to inspect or make tightly supervised edits without inheriting every local customization. It is especially relevant to CI jobs, security reviews, customer repositories, and contributor pull requests where a normal interactive profile has too much ambient configuration.
This is a different task from auditing broad Bash wildcard rules. The earlier Claude Code 2.1.246 Bash permission audit narrows commands after command execution exists. Restricted mode starts one layer earlier by removing command and code tools unless you deliberately add them back.
What changed in 2.1.248
The official release and the installed 2.1.248 CLI help describe the same boundary:
| Surface | Restricted-mode default | Operator decision |
|---|---|---|
| Command and code tools |
Bash, PowerShell, REPL, and other code-running tools are removed |
Restore only a named tool that the task truly needs |
| Web access |
WebFetch is removed |
Do not restore it for repository-only review |
| File tools | Confined to the starting directory and directories named by --add-dir
|
Start in the smallest useful root; review every added directory |
| Settings | User, project, and local settings files are ignored | Managed settings and explicit --settings still need review |
| Permission mode |
bypassPermissions is refused |
Keep human or configured permission handling for protected writes |
| MCP | Existing MCP configuration is a separate surface | Add --strict-mcp-config and an explicit MCP file when isolation matters |
The final row is easy to miss. The CLI help explicitly tells operators to add --strict-mcp-config to skip other MCP servers. Restricted mode therefore should not be described as “no external tools” without checking the resulting MCP inventory.
A six-stage rollout
1. Pin and prove the executable
Record the exact binary before testing policy. A global claude command may point to an older installation even when package metadata shows a newer release.
npm exec --yes --package=@anthropic-ai/claude-code@2.1.248 -- claude --version
npm exec --yes --package=@anthropic-ai/claude-code@2.1.248 -- claude --help
Your evidence should show 2.1.248 and the complete --restricted description. Pinning is not supply-chain approval by itself; use your normal lockfile, checksum, or controlled distribution process for production automation.
2. Start from the smallest working directory
Use a disposable fixture or a narrow checkout that contains no production credentials. Do not start at a home directory or a monorepo root merely for convenience. Add another directory only when the task has a named input there, because --add-dir intentionally enlarges the file-tool boundary.
Restricted mode limits the built-in file tools. It does not claim to virtualize the host filesystem, network, process table, or credentials for arbitrary external programs. If the input is hostile and any executable capability is required, put the whole process inside a hardened container or VM and apply Claude Code sandbox controls as a separate layer.
3. Declare the tool surface instead of inheriting it
For a read-only repository review, make the built-in list explicit:
npm exec --yes --package=@anthropic-ai/claude-code@2.1.248 -- \
claude --restricted \
--tools "Read,Grep,Glob" \
--strict-mcp-config \
--mcp-config ./restricted-mcp.json
Use a reviewed MCP file with no servers when none are needed. If the task requires edits, add the narrow file-edit tool and retain approval for protected files. If it requires a command, prefer a task-specific wrapper or a container rather than restoring broad Bash and assuming the word “restricted” still contains it.
4. Review the settings that still win
Ignoring user, project, and local settings removes ambient repository customization, including convenient rules you may have expected. It does not suppress administrator-managed policy or a file/JSON object passed with --settings. Record both surviving sources and make the explicit settings artifact part of the reviewed job definition.
Do not use ignored local settings as your only denial control. A repository cannot prove its own restricted policy by placing that policy in a settings source the mode intentionally skips.
5. Run eight payload-safe canaries
Use synthetic files and no real credentials or external side effects:
| Canary | Expected evidence |
|---|---|
| Version | Exact output is 2.1.248
|
| Tool inventory | Command/code tools and WebFetch are absent unless explicitly named |
| Local-settings isolation | A harmless user/project/local rule does not change the session |
| Surviving policy | Managed policy or explicit --settings still takes effect |
| Working-root boundary | A fixture inside the root is readable; an unlisted sibling is not available to file tools |
| Added-directory boundary | One deliberate --add-dir works without widening to its parent |
| Permission boundary |
bypassPermissions is rejected and a protected write still needs a person or configured handler |
| MCP boundary | Only servers from the explicit MCP file appear when --strict-mcp-config is present |
Test denials with harmless canary names, not secrets. A failed attempt to read a real credential is already an unnecessary exposure event.
6. Promote one task and keep a rollback
Promote restricted mode by task template, not as a universal secure-profile label. Store the pinned version, launch command, working roots, surviving settings, tool inventory, MCP inventory, canary results, and owner. Roll back by disabling the job or restoring the previous pinned executable; do not “repair” a failure by silently adding broad tools.
Decision tree
Does the task need only built-in file inspection or supervised edits?
yes -> start with --restricted
-> name the minimum --tools
-> use --strict-mcp-config when MCP isolation matters
-> run eight canaries
-> promote one task template
no -> does it need commands, code, WebFetch, or an external MCP tool?
yes -> map that tool's real authority
-> use a container/VM when input is untrusted
-> add only the required capability
-> rerun the boundary canaries
Common mistakes
- Calling
--restricteda sandbox or a guarantee against prompt injection. - Restoring broad
Bash, REPL, orWebFetchand continuing to describe the session as low authority. - Forgetting that
--add-direxpands the file boundary. - Assuming all settings disappear when managed settings and explicit
--settingsstill apply. - Assuming MCP servers disappear without checking
--strict-mcp-configand the actual tool inventory. - Testing a denial against a real secret instead of a synthetic canary.
- Running the newest package through
npm execin production without a controlled integrity and rollback process.
Copyable acceptance record
date / owner / task:
Claude Code version / package integrity:
launch command / working directory / added directories:
built-in tool inventory / restored tools:
managed settings / explicit settings artifact:
MCP file / strict MCP result:
eight canary results:
container or VM boundary, if required:
promotion scope / rollback command:
Building something? Take a 60-sec game break. Score to rank your product or profile on tapto.top and get more exposure—free, no signup.
FAQ
Does restricted mode make an unfamiliar repository safe to open?
It reduces ambient tools and settings, but it is not a complete hostile-repository boundary. Keep workspace trust, prompt-injection review, OS isolation, network controls, and credential separation proportional to the input risk.
Can I use --tools to add Bash back?
The 2.1.248 release says command/code tools and WebFetch are removed unless named in --tools. Adding one back is deliberate authority expansion. Map and contain that authority before doing so.
Are all settings ignored?
No. User, project, and local settings files are ignored. Managed settings and an explicit --settings input still apply, according to the 2.1.248 CLI help.
Is restricted mode the same as Plan mode or dontAsk?
No. Permission modes decide how available tools are approved. Restricted mode first changes which built-in tools, file roots, and settings sources are available. You still need to choose and verify the permission behavior for the resulting surface.
Top comments (1)
I appreciate the thoughtful approach to restricting command and code execution in the new
--restrictedmode. This proactive measure can significantly enhance security, especially in CI environments where minimizing risk is crucial. One perspective to consider is implementing automated tests that validate the configuration and permissions of any tools restored in this mode to ensure compliance with security standards. If you’re exploring further enhancements or need extra development support for this rollout, I’d be glad to discuss a paid collaboration. What challenges have you faced in ensuring user awareness of the new boundaries set by this feature?