Skip to main content

claude_code_settings/
permissions.rs

1//! `permissions`, `autoMode` and the MCP server allow and deny lists.
2
3use alloc::string::String;
4use alloc::vec::Vec;
5
6use serde::{Deserialize, Serialize};
7
8use crate::Extra;
9use crate::enums::{DisableFlag, PermissionMode};
10use crate::walk::walk;
11
12/// `permissions`: rules and the starting mode.
13///
14/// Rules use Claude Code's permission-rule syntax (`Bash(git diff:*)`,
15/// `Read(./src/**)`, `WebFetch(domain:example.com)`, `mcp__server`).
16/// Across layers the lists merge, and a `deny` beats an `allow`.
17///
18/// Control which tools Claude can use without asking, which ones prompt, and which ones are
19/// blocked. Also set the default [permission
20/// mode](https://code.claude.com/docs/en/permission-modes) for new sessions.
21///
22/// Docs: [`permissions`](https://code.claude.com/docs/en/settings-reference#permissions).
23#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
24#[serde(rename_all = "camelCase")]
25#[non_exhaustive]
26pub struct Permissions {
27    /// List the tool uses Claude Code approves without asking you. In an MCP rule, `*` can
28    /// appear only in the tool name after the `mcp__<server>__` prefix, such as
29    /// `mcp__github__get_*`; it can't appear in the server name.
30    ///
31    /// - **Values**: array of permission rule strings
32    /// - **Default**: unset
33    /// - **Scope**: any settings file.
34    ///
35    /// Docs: [`allow`](https://code.claude.com/docs/en/settings-reference#permissions-allow).
36    #[serde(skip_serializing_if = "Option::is_none")]
37    pub allow: Option<Vec<String>>,
38    /// List the tool uses Claude Code blocks. Use it for files that hold API keys, secrets, or
39    /// environment values: Claude Code excludes matching files from file discovery and search
40    /// results, denies reads of them, and blocks the [Edit and Write
41    /// tools](https://code.claude.com/docs/en/permissions#read-and-edit) on the matching paths.
42    /// Read and Edit deny rules apply to Claude's built-in file tools, to file commands Claude
43    /// Code recognizes in Bash, such as `cat`, `head`, `tail`, `sed`, and `tee`, and to the
44    /// targets of Bash [redirections](https://code.claude.com/docs/en/permissions#redirections)
45    /// such as `> file` and `< file`; they don't apply to a command that reads files without
46    /// naming them, such as `grep -r pattern .`, or to arbitrary subprocesses, so for OS-level
47    /// enforcement [enable the sandbox](https://code.claude.com/docs/en/sandboxing).
48    ///
49    /// - **Values**: array of permission rule strings
50    /// - **Default**: unset
51    /// - **Scope**: any settings file.
52    ///
53    /// Docs: [`deny`](https://code.claude.com/docs/en/settings-reference#permissions-deny).
54    #[serde(skip_serializing_if = "Option::is_none")]
55    pub deny: Option<Vec<String>>,
56    /// List the tool uses that prompt you for confirmation even in a permission mode that would
57    /// otherwise approve them, such as `acceptEdits` or `bypassPermissions`. In `dontAsk` mode
58    /// Claude Code denies a matching tool use instead of prompting.
59    ///
60    /// - **Values**: array of permission rule strings
61    /// - **Default**: unset
62    /// - **Scope**: any settings file.
63    ///
64    /// Docs: [`ask`](https://code.claude.com/docs/en/settings-reference#permissions-ask).
65    #[serde(skip_serializing_if = "Option::is_none")]
66    pub ask: Option<Vec<String>>,
67    /// Set the default [permission mode](https://code.claude.com/docs/en/permission-modes) for
68    /// new sessions. When you leave it unset, the [built-in
69    /// default](https://code.claude.com/docs/en/permission-modes#which-mode-a-session-starts-in)
70    /// for your surface applies.
71    ///
72    /// - **Values**: string, one of:
73    ///   - `"default"`: Claude Code runs only reads without asking
74    ///   - `"acceptEdits"`: Claude Code also runs file edits and common filesystem commands
75    ///     such as `mkdir` and `mv` without asking
76    ///   - `"plan"`: Claude Code reads and plans but blocks edits until you approve a plan
77    ///   - `"auto"`: Claude Code runs without routine prompts; before actions such as shell
78    ///     commands and network requests run, a background classifier checks that they align
79    ///     with your request
80    ///   - `"dontAsk"`: Claude Code auto-denies every call that would otherwise prompt, though
81    ///     a [mod](https://code.claude.com/docs/en/plugins/mods/overview) you installed can
82    ///     still approve [some of those
83    ///     calls](https://code.claude.com/docs/en/permissions#precedence-among-rules-hooks-and-mods).
84    ///     File reads inside your working directories, other actions that need no approval, and
85    ///     pre-approved tools still run, apart from reads from [network
86    ///     paths](https://code.claude.com/docs/en/permissions#network-paths)
87    ///   - `"bypassPermissions"`: Claude Code runs everything without asking
88    ///   - `"manual"`: an alias for `"default"`
89    /// - **Default**: unset
90    /// - **Scope**: any settings file. `auto` and `bypassPermissions` don't take effect from
91    ///   project or local settings, so set them in `~/.claude/settings.json` instead.
92    ///
93    /// Docs: [`defaultMode`](https://code.claude.com/docs/en/settings-reference#permissions-defaultmode).
94    #[serde(skip_serializing_if = "Option::is_none")]
95    pub default_mode: Option<PermissionMode>,
96    /// Prevent anyone from entering `bypassPermissions` mode. Claude Code then rejects the
97    /// `--dangerously-skip-permissions` flag, and ignores an [agent
98    /// definition's](https://code.claude.com/docs/en/sub-agents#permission-modes)
99    /// `permissionMode: bypassPermissions`, so the subagent runs with the parent session's
100    /// permission mode.
101    ///
102    /// - **Values**: the string `"disable"`
103    /// - **Default**: unset
104    /// - **Scope**: any settings file. Typically set in [managed
105    ///   settings](https://code.claude.com/docs/en/managed-settings) to enforce organizational
106    ///   policy.
107    ///
108    /// Docs: [`disableBypassPermissionsMode`](https://code.claude.com/docs/en/settings-reference#permissions-disablebypasspermissionsmode).
109    #[serde(skip_serializing_if = "Option::is_none")]
110    pub disable_bypass_permissions_mode: Option<DisableFlag>,
111    /// Set to "disable" to prevent auto mode from being activated. Removes `auto` from the
112    /// Shift+Tab cycle and rejects `--permission-mode auto` at startup. Most useful in managed
113    /// settings where users cannot override it.
114    ///
115    /// - **Values**: `"disable"`
116    /// - **Default**: unset
117    ///
118    /// Docs: [`disableAutoMode`](https://code.claude.com/docs/en/settings-reference#permissions).
119    #[serde(skip_serializing_if = "Option::is_none")]
120    pub disable_auto_mode: Option<DisableFlag>,
121    /// Give Claude file access to directories outside the one you started in, as additional
122    /// [working directories](https://code.claude.com/docs/en/permissions#working-directories).
123    /// Most `.claude/` configuration is [not
124    /// discovered](https://code.claude.com/docs/en/permissions#additional-directories-grant-file-access-not-configuration)
125    /// from these directories.
126    ///
127    /// - **Values**: array of directory paths
128    /// - **Default**: unset
129    /// - **Scope**: any settings file, with [limits on the sandbox write
130    ///   access](https://code.claude.com/docs/en/sandboxing#repository-settings-under-an-admin-required-sandbox)
131    ///   that project and local entries give.
132    ///
133    /// Docs: [`additionalDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-additionaldirectories).
134    #[serde(skip_serializing_if = "Option::is_none")]
135    pub additional_directories: Option<Vec<String>>,
136    /// Make Claude's file tools refuse reads outside your [working
137    /// directories](https://code.claude.com/docs/en/permissions#working-directories) in every
138    /// permission mode, including `bypassPermissions`. Claude Code denies `Read`, `Grep`,
139    /// `Glob`, and `LSP` calls on those paths and tells Claude to ask you to add the directory
140    /// with `/add-dir`. Files Claude Code itself needs stay readable, such as your skills,
141    /// plugins, rules, agents, commands, and the `CLAUDE.md` memory file under `~/.claude/`.
142    ///
143    /// - **Values**: Boolean
144    ///   - `true`: Claude's file tools refuse reads outside the working directories
145    ///   - `false`: the same as unset; the block still applies if another file sets `true`
146    /// - **Default**: unset, so reads outside the working directories follow your [permission
147    ///   mode](https://code.claude.com/docs/en/permission-modes)
148    /// - **Scope**: any settings file. A `true` in any file applies, so a repository can turn
149    ///   the block on for itself but can't lift yours.
150    ///
151    /// Docs: [`blockReadsOutsideWorkingDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-blockreadsoutsideworkingdirectories).
152    #[serde(skip_serializing_if = "Option::is_none")]
153    pub block_reads_outside_working_directories: Option<bool>,
154    /// Make the `Write`, `Edit`, and `NotebookEdit` tools refuse paths outside your [working
155    /// directories](https://code.claude.com/docs/en/permissions#working-directories) in every
156    /// permission mode, including `bypassPermissions`, apart from [some of Claude Code's own
157    /// files](https://code.claude.com/docs/en/settings-reference#what-the-write-block-refuses-and-what-stays-writable).
158    /// The key doesn't limit shell commands, MCP tools, or the programs hooks run. To limit
159    /// where shell commands write, turn on
160    /// [sandboxing](https://code.claude.com/docs/en/sandboxing).
161    ///
162    /// - **Values**: Boolean
163    ///   - `true`: turns the block on
164    ///   - `false`: the same as unset; the block still applies if another file sets `true`
165    /// - **Default**: unset, so writes outside the working directories follow your [permission
166    ///   mode](https://code.claude.com/docs/en/permission-modes). The block is also on while
167    ///   Claude Code can't read the `permissions` object in your [managed
168    ///   settings](https://code.claude.com/docs/en/managed-settings#keys-that-fail-closed).
169    /// - **Scope**: any settings file. A `true` in any file the session loads applies, so a
170    ///   repository can turn the block on for itself but can't lift yours.
171    ///
172    /// Docs: [`blockWritesOutsideWorkingDirectories`](https://code.claude.com/docs/en/settings-reference#permissions-blockwritesoutsideworkingdirectories).
173    #[serde(skip_serializing_if = "Option::is_none")]
174    pub block_writes_outside_working_directories: Option<bool>,
175    /// Set this to `true` to keep a session running when nobody is there to answer a permission
176    /// prompt. Claude Code denies a tool call that would otherwise wait on a prompt, and the
177    /// turn continues. Requires Claude Code v2.1.319 or later.
178    ///
179    /// - **Values**: Boolean
180    ///   - `true`: Claude Code denies calls that would otherwise prompt
181    ///   - `false`: the same as unset; calls are still denied if another of these sources sets
182    ///     `true`
183    /// - **Default**: unset, so a call that needs approval prompts you
184    /// - **Scope**: user or managed, and `--settings`. A repository can't set it for you.
185    ///
186    /// Docs: [`denyInsteadOfPrompting`](https://code.claude.com/docs/en/settings-reference#permissions-denyinsteadofprompting).
187    #[serde(skip_serializing_if = "Option::is_none")]
188    pub deny_instead_of_prompting: Option<bool>,
189    /// Keys Claude Code accepts here that this crate doesn't model (newer or
190    /// undocumented ones), kept as written so the document round-trips.
191    #[serde(flatten)]
192    pub extra: Extra,
193}
194
195/// `autoMode`: the auto-mode classifier's sections. Each list replaces
196/// the built-in one unless it holds the literal `$defaults`.
197///
198/// Add your own rules to what the [auto
199/// mode](https://code.claude.com/docs/en/permission-modes#eliminate-prompts-with-auto-mode)
200/// classifier blocks and allows. Use it to tell the classifier which repos, buckets, and
201/// domains your organization trusts, so it stops blocking routine internal operations.
202///
203/// Docs: [`autoMode`](https://code.claude.com/docs/en/settings-reference#automode).
204#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
205#[serde(rename_all = "camelCase")]
206#[non_exhaustive]
207pub struct AutoMode {
208    /// Rules for the auto mode classifier allow section. Replaces the built-in allow rules
209    /// entirely unless the literal string "$defaults" is included as an entry, which splices
210    /// the built-in defaults in at that position.
211    ///
212    /// - **Values**: array of strings
213    /// - **Default**: unset
214    ///
215    /// Docs: [`allow`](https://code.claude.com/docs/en/settings-reference#automode).
216    #[serde(skip_serializing_if = "Option::is_none")]
217    pub allow: Option<Vec<String>>,
218    /// Rules for the auto mode classifier soft-deny section. Replaces the built-in soft-deny
219    /// rules entirely unless the literal string "$defaults" is included as an entry, which
220    /// splices the built-in defaults in at that position.
221    ///
222    /// - **Values**: array of strings
223    /// - **Default**: unset
224    ///
225    /// Docs: [`soft_deny`](https://code.claude.com/docs/en/settings-reference#automode).
226    #[serde(rename = "soft_deny", skip_serializing_if = "Option::is_none")]
227    pub soft_deny: Option<Vec<String>>,
228    /// Entries for the auto mode classifier environment section. Replaces the built-in
229    /// environment context entirely unless the literal string "$defaults" is included as an
230    /// entry, which splices the built-in defaults in at that position.
231    ///
232    /// - **Values**: array of strings
233    /// - **Default**: unset
234    ///
235    /// Docs: [`environment`](https://code.claude.com/docs/en/settings-reference#automode).
236    #[serde(skip_serializing_if = "Option::is_none")]
237    pub environment: Option<Vec<String>>,
238    /// Rules for the auto mode classifier hard-deny section. Hard-deny rules block
239    /// unconditionally regardless of user intent. Replaces the built-in hard-deny rules
240    /// entirely unless the literal string "$defaults" is included as an entry, which splices
241    /// the built-in defaults in at that position.
242    ///
243    /// - **Values**: array of strings
244    /// - **Default**: unset
245    ///
246    /// Docs: [`hard_deny`](https://code.claude.com/docs/en/settings-reference#automode).
247    #[serde(rename = "hard_deny", skip_serializing_if = "Option::is_none")]
248    pub hard_deny: Option<Vec<String>>,
249    /// Send every Bash and PowerShell command through the auto mode classifier while auto mode
250    /// is active. By default, auto mode suspends only allow rules that could run arbitrary
251    /// code: tool-wide and wildcard rules such as `Bash(*)`, and interpreter or shell-wrapper
252    /// prefixes such as `Bash(python *)`. A command that any other allow rule matches, such as
253    /// `Bash(npm test)`, skips the classifier unless it carries [per-command allowed
254    /// domains](https://code.claude.com/docs/en/sandboxing#per-command-allowed-domains-in-auto-mode).
255    ///
256    /// - **Values**: Boolean
257    ///   - `true`: while auto mode is active, Claude Code sends every Bash and PowerShell
258    ///     command through the classifier and suspends your shell allow rules; outside auto
259    ///     mode the rules still apply
260    ///   - `false`: auto mode suspends only allow rules that could run arbitrary code, such as
261    ///     `Bash(*)` and `Bash(python *)`; a command that any other allow rule matches skips
262    ///     the classifier unless it carries [per-command allowed
263    ///     domains](https://code.claude.com/docs/en/sandboxing#per-command-allowed-domains-in-auto-mode),
264    ///     and every other shell command goes through it
265    /// - **Default**: `false`
266    /// - **Scope**: user or managed. Read wherever automode is read.
267    ///
268    /// Docs: [`classifyAllShell`](https://code.claude.com/docs/en/settings-reference#automode-classifyallshell).
269    #[serde(skip_serializing_if = "Option::is_none")]
270    pub classify_all_shell: Option<bool>,
271    /// Keys Claude Code accepts here that this crate doesn't model (newer or
272    /// undocumented ones), kept as written so the document round-trips.
273    #[serde(flatten)]
274    pub extra: Extra,
275}
276
277/// An entry of `allowedMcpServers` or `deniedMcpServers`: one of the
278/// three fields.
279///
280/// Allowlist the MCP servers people can add. Claude Code blocks any server that doesn't match
281/// an entry wherever it's defined, including plugin servers, servers a user passes with
282/// `--mcp-config`, and servers from claude.ai.
283///
284/// Docs: [`allowedMcpServers`](https://code.claude.com/docs/en/settings-reference#allowedmcpservers).
285#[derive(Debug, Clone, Default, PartialEq, Serialize, Deserialize)]
286#[serde(rename_all = "camelCase")]
287#[non_exhaustive]
288pub struct McpServerRule {
289    /// Name of the MCP server that users are allowed to configure.
290    ///
291    /// - **Values**: string
292    /// - **Default**: unset
293    ///
294    /// Docs: [`serverName`](https://code.claude.com/docs/en/settings-reference#allowedmcpservers).
295    #[serde(skip_serializing_if = "Option::is_none")]
296    pub server_name: Option<String>,
297    /// Exact command and arguments used to start stdio servers.
298    ///
299    /// - **Values**: array of strings
300    /// - **Default**: unset
301    ///
302    /// Docs: [`serverCommand`](https://code.claude.com/docs/en/settings-reference#allowedmcpservers).
303    #[serde(skip_serializing_if = "Option::is_none")]
304    pub server_command: Option<Vec<String>>,
305    /// URL pattern for remote servers, supports wildcards (e.g., <https://*.example.com/*>).
306    ///
307    /// - **Values**: string
308    /// - **Default**: unset
309    ///
310    /// Docs: [`serverUrl`](https://code.claude.com/docs/en/settings-reference#allowedmcpservers).
311    #[serde(skip_serializing_if = "Option::is_none")]
312    pub server_url: Option<String>,
313    /// Keys Claude Code accepts here that this crate doesn't model (newer or
314    /// undocumented ones), kept as written so the document round-trips.
315    #[serde(flatten)]
316    pub extra: Extra,
317}
318
319walk!(Permissions {});
320walk!(AutoMode {});
321walk!(McpServerRule {});