Claude Code restricted mode: a security audit for business workflows

Claude Code restricted mode is designed to reduce what a session can do, but enabling it does not by itself make an AI development workflow safe for production. Anthropic added the --restricted flag, with CLAUDE_CODE_RESTRICTED=1 as an environment-variable alternative, in Claude Code 2.1.248 on August 27, 2026. Anthropic says the mode removes built-in tools that run commands or code and removes WebFetch unless those tools are explicitly named through --tools. File tools remain confined to the working directory, bypassPermissions is refused, and user, project and local settings files are ignored.

The shortest decision sequence is: define the task, begin with the least access it needs, record any exception, test the resulting output and require an accountable human decision. Restricted mode can support that sequence, but it cannot replace it. Anthropic does not claim that the flag certifies a workflow, eliminates every risk or guarantees correct code.

The same release introduced several adjacent controls and diagnostics. Anthropic added an experimental per-agent prompt-cache setting named experimental.cacheTtl, accepting the documented values 5m or 1h when no subagent TTL setting is configured. It also added startup, /doctor and /status diagnostics for failures involving server-managed settings. Cross-session messaging was extended to sessions on the same machine in the named environments, including when telemetry is disabled.

The changelog also records fixes for prompt-cache misses, resumed sessions and transcript cleanup. Claude Code 2.1.250 followed on August 28 with bug fixes and reliability improvements, but Anthropic’s entry does not specify their individual scope. Do not convert that short description into a claim that every reliability issue has been resolved. Restricted mode is an access-reduction feature; cache configuration, diagnostics and reliability fixes solve different operational problems.

The right question is not whether restricted mode is universally better. It is whether a task genuinely requires capabilities that the mode removes. A task-and-evidence matrix makes that decision visible before a session starts.

• Read-only repository review: prefer restricted mode; evidence is the assigned working directory and a saved review brief; the engineering owner verifies that no execution is required.
• Content or configuration editing inside one repository: begin restricted; evidence is a bounded file list and diff; the repository owner approves the changes.
• Dependency installation, builds or test commands: restricted mode may be insufficient because command execution is removed; document the required command, use an isolated environment and require engineer approval.
• External documentation retrieval: WebFetch is unavailable unless expressly named through --tools; record why external access is required, which tool is enabled and who approved it.
• Deployment, infrastructure mutation or secret-bearing work: do not treat restricted mode as deployment authorization; separate credentials, environment permissions and release approval remain necessary.

The decision rule is simple: start with the least capability that can complete the defined task. Add a tool only when its necessity, scope, owner and validation method are written down.

A useful pilot should test a real but reversible task. Avoid beginning with production deployment or a broad autonomous refactor. Select a bounded repository, remove live credentials from the working context and define the expected artifact before launching the session.

1. Write a task contract containing permitted files, prohibited actions, expected output and acceptance tests.
2. Launch Claude Code with --restricted or the documented environment variable. Capture the command and installed version in the run record.
3. Confirm that command-running and code-execution tools are absent. Check that WebFetch is absent unless it was deliberately named through --tools.
4. Attempt a harmless file operation outside the working directory and record whether confinement behaves as expected. Do not use sensitive data for this test.
5. Confirm that bypassPermissions is refused and that ignored user, project and local settings do not contain assumptions required by the task.
6. Review the resulting diff manually, run tests in a separately controlled step and retain both reviewer identity and disposition.
7. Promote the workflow only if the observed controls match the task contract. Otherwise reduce scope or redesign the execution environment.

This is an operational pilot framework, not a certification sequence published by Anthropic. Adapt it to the repository, data, infrastructure and approval responsibilities involved.

A buyer should expect an inspectable control register rather than a verbal assurance that an agent is sandboxed. For every workflow, assign evidence, corrective action and a named owner.

• Version evidence — installed Claude Code version and run timestamp; action: compare with the approved baseline; owner: platform engineer.
• Launch evidence — command or environment configuration showing restricted mode; action: correct uncontrolled launch templates; owner: automation engineer.
• Tool evidence — effective tool inventory, including any explicit --tools exceptions; action: remove unjustified tools; owner: security reviewer.
• Scope evidence — repository path and permitted file list; action: narrow the working directory; owner: repository maintainer.
• Settings evidence — assumptions that would otherwise come from ignored settings files; action: move required instructions into the approved task contract; owner: technical lead.
• Output evidence — diff, test result and review decision; action: reject or remediate unverified changes; owner: code reviewer.
• Exception evidence — business reason, duration and approver for expanded capabilities; action: expire access after use; owner: system owner.

Missing evidence should produce a failed audit item, not a guessed pass. The register should also show who can close a finding and what proof is required before closure.

Measure whether the workflow remains within its declared boundary and produces reviewable output. A controlled pilot can track the share of runs launched with the approved restricted configuration, the number of explicit tool exceptions, attempted out-of-scope actions, review rejection reasons, test status and time required for human verification. These are suggested internal operating measures, not performance figures supplied by Anthropic.

For business automation, connect technical acceptance to the downstream process. A change is not successful merely because Claude Code completed a task. It must pass the relevant tests, preserve required data handling, receive accountable approval and produce the intended business artifact. If the workflow supports lead operations, qualified leads should be measured from agreed CRM stages and sales dispositions rather than raw form submissions. Restricted mode does not define attribution or lead quality.

Compare restricted and expanded-capability runs only on matched task classes. Otherwise a faster result may simply reflect broader permissions rather than a better operating model. Record differences as observations, not as universal performance conclusions.

Do not assume that working-directory confinement is equivalent to a complete operating-system sandbox. Anthropic’s changelog states how file tools behave in restricted mode, but it does not document a general security certification in this release entry. Do not assume ignored settings are harmless either: a task may silently depend on instructions previously stored in user, project or local configuration. Reconstruct necessary assumptions explicitly before execution.

• Do not assume restricted mode validates generated code or factual conclusions.
• Do not assume it manages repository permissions, cloud roles, deployment credentials or external approvals.
• Do not add WebFetch through --tools as a convenience; treat it as an explicit access exception.
• Do not interpret the cache TTL option as a security boundary. It is a separate experimental cache configuration.
• Do not interpret the 2.1.250 reliability note as proof that all defects are fixed.
• Do not let cross-session messaging replace an auditable task and approval record.

The remaining control is human accountability: somebody must own scope, review evidence and accept or reject the output.

A credible provider should offer more than installation. Ask for a workflow inventory, task-risk classification, tool-permission map, repository isolation design, settings-dependency review, exception procedure, test plan, reviewer matrix and retained run evidence. Require the proposal to distinguish Anthropic’s documented product behavior from the provider’s own recommended controls.

For a concrete next step, request a scoped proposal for an AI automation control pack containing a task-boundary register, tool-permission map, exception log template, acceptance-test plan and human-approval matrix. Use the AI automation service page to assess fit and confirm exactly which deliverables, systems and responsibilities would be included before engagement.

To continue the diagnosis, describe your repository, the tasks you want to delegate, the tools the agent may need, the data involved and who currently approves changes. Share that operating context with Lia and ask for a review of the required scope, evidence and approval points. Lia’s response should be treated as the start of scoping, not as proof that a particular implementation service or outcome is available.

What does Claude Code restricted mode remove?

Anthropic says it removes built-in tools that run commands or code and removes WebFetch unless a tool is explicitly named through --tools. File tools remain limited to the working directory.

How is restricted mode enabled?

Anthropic documents the --restricted flag and the CLAUDE_CODE_RESTRICTED=1 environment variable in Claude Code 2.1.248.

Does restricted mode allow bypassPermissions?

No. Anthropic states that restricted mode refuses bypassPermissions.

Are project settings still loaded?

Anthropic says restricted mode ignores user, project and local settings files. Required task instructions should therefore be made explicit and reviewed.

Does restricted mode make generated code production-ready?

No such guarantee is stated. Code still requires testing, security review, change approval and controlled deployment.

What should an audit produce?

A useful audit should produce a version record, launch evidence, effective tool inventory, scope definition, exception log, output diff, test results and named approval owner.