One read of Claude Code CLIclaude-code-20261104T183701Z
9 pages moved out of 228 read.
Pages moved
9
significant first
Pages read
228
in this capture
Captured
18:37 UTC
Corpus hash
6dac710a4028
corpus-hash
What this read moved
1-9 of 9agent-sdk/agent-loop Changed · +3 / -3 lines
from line 227
227227| Mode | Behavior | Use case |
228228| :- | :- | :- |
229229| `"default"` | Tool calls that need approval and aren't covered by allow rules trigger your `canUseTool` callback; no callback means deny | Interactive applications with a custom approval callback |
230| `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.); other Bash commands follow default rules | You trust Claude's edits and want faster iteration, such as during prototyping or when working in an isolated directory |
231| `"plan"` | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback | You want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they're made |
230| `"acceptEdits"` | Auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) inside your [working directories](https://code.claude.com/docs/en/permissions.md#working-directories); other Bash commands follow default rules | You trust Claude's edits and want faster iteration, such as during prototyping or when working in an isolated directory |
231| `"plan"` | Claude explores and plans. Edits made with Claude's file tools go to your `canUseTool` callback even when an allow rule matches them | You want Claude to produce a plan first, such as during code review or before a large change |
232232| `"dontAsk"` | Never prompts. Tools pre-approved by [permission rules](https://code.claude.com/docs/en/settings-reference.md#permission-settings) run, and so do calls that need no approval in `default` mode, such as file reads inside your working directories. Every call that would otherwise prompt is denied, though a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) you installed can still approve [some of those calls](https://code.claude.com/docs/en/permissions.md#precedence-among-rules-hooks-and-mods). A few calls, such as [reads from network paths](https://code.claude.com/docs/en/permissions.md#network-paths), are denied even if you've allowed them. For the list, see [Don't ask mode](https://code.claude.com/docs/en/agent-sdk/permissions.md#don’t-ask-mode-dontask) | Headless agents with nobody to approve calls |
233233| `"auto"` | Uses a model classifier to review actions such as shell commands and network requests, allowing or blocking each one it reviews. See [Auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) for availability and the decision order | Autonomous agents that still want safety guardrails on tool use |
234234| `"bypassPermissions"` | Runs tool calls without asking for approval, including calls to tools you didn't list in `allowedTools`. A few calls still go to your `canUseTool` callback, listed under [Bypass permissions mode](https://code.claude.com/docs/en/agent-sdk/permissions.md#bypass-permissions-mode-bypasspermissions). In the TypeScript SDK, also requires `allowDangerouslySkipPermissions: true` in `options`. Can't be used when running as root on Unix. Use only in isolated environments where the agent's actions can't affect systems you care about | CI, containers, or other isolated environments |
235235
236For interactive applications, use `"default"` with a tool approval callback to surface approval prompts. For autonomous agents on a dev machine, `"acceptEdits"` auto-approves file edits and common filesystem commands (`mkdir`, `touch`, `mv`, `cp`, etc.) while still gating other `Bash` commands behind allow rules. Reserve `"bypassPermissions"` for CI, containers, or other isolated environments. See [Permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md) for full details.
236For interactive applications, use `"default"` with a tool approval callback to surface approval prompts. For agents that edit files on a dev machine, use `"acceptEdits"`. Reserve `"bypassPermissions"` for CI, containers, or other isolated environments. See [Permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md) for full details.
237237
238238### Model
239239
agent-sdk/permissions Changed · +58 / -31 lines
### Path patterns in rules
from line 10
1010>
1111> If you load a plugin that contains a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md), see [where a mod's decisions fit among rules and hooks](https://code.claude.com/docs/en/permissions.md#precedence-among-rules-hooks-and-mods).
1212
13When Claude requests a tool, the SDK checks permissions in this order:
13When Claude requests a tool, Claude Code checks the call at these steps. Each step can decide the call, send it to your `canUseTool` callback, or pass it on:
1414
1515**1. Hooks**
1616
17Run [hooks](https://code.claude.com/docs/en/agent-sdk/hooks.md) first. A hook can deny the call outright or pass it on. A hook that returns `allow` doesn't skip the deny and ask rules below, which are evaluated regardless of the hook result.
17Run [hooks](https://code.claude.com/docs/en/agent-sdk/hooks.md). A hook can deny the call outright or pass it on. A hook that returns `allow` doesn't skip the deny and ask rules below, which are evaluated regardless of the hook result.
1818
1919A `PreToolUse` hook that returns `allow` also can't approve an `rm` or `rmdir` command whose target Claude Code recognizes as a [critical path](https://code.claude.com/docs/en/permission-modes.md#critical-paths), such as `rm -rf ~`. For what that `allow` does in plan mode, see [Hook approvals in plan mode](https://code.claude.com/docs/en/permissions.md#hook-approvals-in-plan-mode).
2020
2121**2. Deny rules**
2222
23If a deny rule from `disallowed_tools` or [settings.json](https://code.claude.com/docs/en/settings-reference.md#permission-settings) matches, the call is denied and [`canUseTool`](https://code.claude.com/docs/en/agent-sdk/user-input) isn't called, even in [`bypassPermissions`](#bypass-permissions-mode-bypasspermissions) mode and even when a hook returned `allow`.
23If a deny rule from `disallowed_tools` or from a [settings file the SDK loads](#rules-in-settings-files) matches, the call is denied and [`canUseTool`](https://code.claude.com/docs/en/agent-sdk/user-input) isn't called. The call is denied this way even in [`bypassPermissions`](#bypass-permissions-mode-bypasspermissions) mode and when a hook returned `allow`.
2424
2525In the TypeScript SDK, if you set the `permission_policy` of a [custom tool](https://code.claude.com/docs/en/agent-sdk/custom-tools.md#require-approval-for-specific-tools) to [`always_deny`](https://code.claude.com/docs/en/agent-sdk/typescript#mcpservertoolpolicy), a call to that tool is denied at this step.
2626
from line 28
2828
2929Check `ask` rules from [settings.json](https://code.claude.com/docs/en/settings-reference.md#permission-settings). If an ask rule matches, the call falls through to your [`canUseTool` callback](https://code.claude.com/docs/en/agent-sdk/user-input) for confirmation, even in `bypassPermissions` mode.
3030
31Tools that require user interaction behave the same way: `AskUserQuestion` and MCP tools whose server sets [`_meta["anthropic/requiresUserInteraction"]`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool) always fall through to the callback, even when an allow rule matches. In `dontAsk` mode both cases are denied instead, because that mode never prompts. The MCP annotation requires Claude Code v2.1.199 or later.
31Tools that require user interaction behave the same way. `AskUserQuestion` and MCP tools whose server sets [`_meta["anthropic/requiresUserInteraction"]`](https://code.claude.com/docs/en/mcp#require-approval-for-a-specific-tool) fall through to the callback, even when an allow rule matches. In `dontAsk` mode both cases are denied instead, because that mode turns each prompt into a denial. The MCP annotation requires Claude Code v2.1.199 or later.
3232
3333[claude.ai connector](https://code.claude.com/docs/en/mcp.md#organization-controls-on-connector-tools) tools your organization has set to `ask` also leave the flow at this step. Every call falls through to the callback, even in `bypassPermissions` mode and even when an allow rule matches. The callback receives the reason `Your organization requires approval for this tool`. In `dontAsk` mode the call is denied instead, because that mode never prompts.
3434
from line 38
3838
3939Apply the active [permission mode](#permission-modes):
4040
41* In `bypassPermissions` mode, Claude Code approves everything that reaches this step except recognized [critical-path removals](https://code.claude.com/docs/en/permission-modes.md#critical-paths) and Bash commands flagged [`Dangerous rm operation not ruled out`](https://code.claude.com/docs/en/permission-modes#dangerous-rm-operation-not-ruled-out), which fall through instead.
42 * To run those removals with no prompt, see [Turn off the critical-path removal prompt](https://code.claude.com/docs/en/permission-modes.md#turn-off-the-critical-path-removal-prompt-in-bypasspermissions-mode).
41* In `bypassPermissions` mode, Claude Code approves each call that reaches this step unless it's one of the [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves). For which of those actions go to your `canUseTool` callback, see [Bypass permissions mode](#bypass-permissions-mode-bypasspermissions).
4342* In `acceptEdits` mode, Claude Code approves the file operations listed under [Accept edits mode](#accept-edits-mode-acceptedits).
44* In `plan` mode, Claude Code sends file-edit tools to your `canUseTool` callback regardless of allow rules.
45* In other modes, the request falls through.
43* In `plan` mode, some calls reach your callback, and when auto mode is available, others go to its classifier instead. For more information, see [Plan mode](#plan-mode-plan).
44* In `default` and `dontAsk` mode, the call goes on to the allow rules.
45* For `auto` mode, see [Auto mode](#auto-mode-auto).
4646
4747**5. Allow rules**
4848
from line 87
8787
8888Allow rules accept tool-name globs only after a literal `mcp__<server>__` prefix. The server segment must be glob-free so the rule names a specific server you configured: `mcp__puppeteer__*` matches every tool from the `puppeteer` server, and `mcp__github__get_*` matches its `get_` tools. An unanchored entry like `allowed_tools=["*"]` or `allowed_tools=["mcp__*"]` is ignored and doesn't auto-approve anything.
8989
90Scoped rules for `Read` and `Edit` take a path pattern. `Edit(path)` rules govern all built-in tools that write files, including `Write` and `NotebookEdit`; a `Write(path)` rule is never matched by the file permission checks.
91
92Use `//path` for an absolute filesystem path: a deny rule of `Edit(//secrets/**)` blocks writes anywhere under `/secrets` on disk. With a single leading slash, `Edit(/secrets/**)` anchors at the rule's source instead. For rules passed through `allowed_tools` or `disallowed_tools`, that means the session's working directory, so the rule doesn't block `/secrets` on disk. See [Read and Edit rules](https://code.claude.com/docs/en/permissions.md#read-and-edit) for the four anchor forms and how rules from settings files resolve.
93
9490> [!WARNING]
9591>
9692> **Auto-approved tools never reach `canUseTool`.** A tool call approved at any earlier step, by `acceptEdits` or `bypassPermissions`, or by an allow rule, skips your `canUseTool` callback, so permission checks you put there are silently bypassed for that tool.
from line 97
10197>
10298> * Custom tools your application marks [`always_ask`](https://code.claude.com/docs/en/agent-sdk/custom-tools#require-approval-for-specific-tools): decide the call in the callback. To stop these calls arriving, [change the policy mid-session](https://code.claude.com/docs/en/agent-sdk/typescript.md#mcpsdkserverconfigwithinstance). In `auto`, `plan`, and `bypassPermissions` mode the call can instead be approved before the callback, in the cases listed under [Permission modes that can approve an `always_ask` call](https://code.claude.com/docs/en/agent-sdk/typescript#permission-modes-that-can-approve-an-always_ask-call)
10399>
104> * Recognized `rm` and `rmdir` [critical-path removals](https://code.claude.com/docs/en/permission-modes.md#critical-paths): in `default`, `acceptEdits`, and `bypassPermissions` mode, allow or deny the removal in the callback, where [`decisionReason`](https://code.claude.com/docs/en/agent-sdk/typescript#canusetool) starts with `Dangerous rm`. For `auto` and `plan` mode, see [Critical-path removals in each permission mode](https://code.claude.com/docs/en/permission-modes.md#critical-path-removals-in-each-permission-mode). The check that recognizes these removals [can miss some commands](https://code.claude.com/docs/en/permission-modes.md#critical-paths)
100> * Recognized `rm` and `rmdir` [critical-path removals](https://code.claude.com/docs/en/permission-modes.md#critical-paths): in `default`, `acceptEdits`, and `bypassPermissions` mode, allow or deny the removal in the callback, where [`decisionReason`](https://code.claude.com/docs/en/agent-sdk/typescript#canusetool) starts with `Dangerous rm`. For `auto` and `plan` mode, see [Critical-path removals in each permission mode](https://code.claude.com/docs/en/permission-modes.md#critical-path-removals-in-each-permission-mode)
105101>
106102> * **Bare name**: an entry like `Read` or `mcp__github__get_issue` auto-approves every call to that tool apart from the [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves) and [reads from network paths](https://code.claude.com/docs/en/permissions.md#network-paths).
107103>
108> * **Scoped rule**: an entry like `Bash(npm test *)` auto-approves only matching calls, and other `Bash` calls that need approval still fall through to the callback.
104> * **Scoped rule**: an entry like `Bash(npm test *)` auto-approves calls that match it, and other `Bash` calls that need approval fall through to the permission mode.
109105>
110> For checks that must run on every tool call, use a [`PreToolUse` hook](https://code.claude.com/docs/en/agent-sdk/hooks): hooks run before every other step, and a hook deny applies even in `bypassPermissions` mode.
106> To check calls that an allow rule, `acceptEdits`, or `bypassPermissions` approves, use a [`PreToolUse` hook](https://code.claude.com/docs/en/agent-sdk/hooks), which runs for those calls too. A hook deny applies even in `bypassPermissions` mode.
111107
112108For a locked-down agent, pair `allowedTools` with `permissionMode: "dontAsk"`:
113109
from line 120
124120
125121> [!WARNING]
126122>
127> **`allowed_tools` does not constrain `bypassPermissions`.** `allowed_tools` pre-approves the tools you list. Other unlisted tools are not matched by any allow rule and fall through to the permission mode, where `bypassPermissions` approves them. Setting `allowed_tools=["Read"]` alongside `permission_mode="bypassPermissions"` still approves every tool, including `Bash`, `Write`, and `Edit`. If you need `bypassPermissions` but want specific tools blocked, use `disallowed_tools`.
123> **`allowed_tools` does not constrain `bypassPermissions`.** `allowed_tools` pre-approves the tools you list. In `bypassPermissions` mode, Claude Code approves a call to an unlisted tool unless it's one of the [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves).
124>
125> If you set `allowed_tools=["Read"]` with `permission_mode="bypassPermissions"`, Claude Code still approves calls to tools such as `Bash`, `Write`, and `Edit`. If you need `bypassPermissions` but want specific tools blocked, use `disallowed_tools`. For the calls that still reach your `canUseTool` callback in this mode, see [Bypass permissions mode](#bypass-permissions-mode-bypasspermissions).
128126
129127You can also configure allow, deny, and ask rules declaratively in `.claude/settings.json`. These rules are read when the `project` setting source is enabled, which it is for default `query()` options. If you set `setting_sources` (TypeScript: `settingSources`) explicitly, include `"project"` for them to apply. See [Permission settings](https://code.claude.com/docs/en/settings-reference.md#permission-settings) for the rule syntax.
130128
129For when allow rules in a project's `.claude/settings.json` apply, see [Project allow rules and workspace trust](https://code.claude.com/docs/en/permissions.md#project-allow-rules-and-workspace-trust).
130
131### Path patterns in rules
132
133Scoped rules for `Read` and `Edit` take a path pattern. `Edit(path)` rules govern all built-in tools that write files, including `Write` and `NotebookEdit`, so write a path rule for any of them as `Edit(path)`. If you write a path rule as `Write(path)` or `NotebookEdit(path)`, it [matches no call](https://code.claude.com/docs/en/permissions.md#path-rules-that-never-match) and has no effect.
134
135In `allowed_tools` and `disallowed_tools`, start a path pattern with `//` for an absolute path, or with a single `/` for a path inside the session's working directory:
136
137* **`//path`**: with a deny rule of `Edit(//secrets/**)`, Claude Code blocks writes under `/secrets` on disk from Claude's file tools and from [Bash commands such as `tee` and `> file` redirection](https://code.claude.com/docs/en/permissions#what-read-and-edit-rules-cover). A script that Claude runs and that opens files itself can still write under `/secrets`. For enforcement by the operating system, see [Configure the sandboxed Bash tool](https://code.claude.com/docs/en/sandboxing.md).
138* **`/path`**: `Edit(/secrets/**)` matches the `secrets` directory inside the working directory.
139
140For other ways to start a path pattern, see [Read and Edit rules](https://code.claude.com/docs/en/permissions.md#read-and-edit).
141
131142## Permission modes
132143
133144Permission modes provide global control over how Claude uses tools. You can set the permission mode when calling `query()` or change it dynamically during streaming sessions.
from line 153
142153| :- | :- | :- |
143154| `default` | Standard permission behavior | No mode-based auto-approvals; calls that need approval and match no allow rule trigger your `canUseTool` callback |
144155| `dontAsk` | Deny instead of prompting | Any call that would otherwise prompt is denied without calling `canUseTool`, though a [mod](https://code.claude.com/docs/en/plugins/mods/overview.md) you installed can still approve [some of those calls](https://code.claude.com/docs/en/permissions.md#precedence-among-rules-hooks-and-mods). Calls approved by `allowed_tools` or `settings.json` allow rules run, and so do calls that need no approval in `default` mode. Some calls, such as [reads from network paths](https://code.claude.com/docs/en/permissions.md#network-paths), are denied even when `allowed_tools` or an allow rule matches them. For the list, see [Don't ask mode](#don’t-ask-mode-dontask) |
145| `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) are automatically approved |
156| `acceptEdits` | Auto-accept file edits | File edits and [filesystem operations](#accept-edits-mode-acceptedits) (`mkdir`, `rm`, `mv`, etc.) inside your [working directories](https://code.claude.com/docs/en/permissions.md#working-directories) are automatically approved |
146157| `bypassPermissions` | Bypass permission checks | Tools run without permission prompts, except for the [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves) and, outside a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md), custom tools your application [marks `always_ask`](https://code.claude.com/docs/en/agent-sdk/custom-tools#require-approval-for-specific-tools). Use with caution |
147| `plan` | Planning mode | Claude explores and plans without editing your source files; file edits are never auto-approved and prompt through your `canUseTool` callback |
158| `plan` | Planning mode | Claude explores and plans. Edits made with Claude's file tools go to your `canUseTool` callback even when an allow rule matches them |
148159| `auto` | Model-classified approvals | A model classifier reviews actions such as shell commands and network requests, allowing or blocking each one it reviews. See [Auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) for availability and the decision order |
149160
150161> [!WARNING]
from line 274
263274
264275**Auto-approved operations:**
265276
266* File edits (Edit, Write tools)
277* File edits with the Edit, Write, and NotebookEdit tools
267278* Filesystem commands: `mkdir`, `touch`, `rm`, `rmdir`, `mv`, `cp`, `sed`
268279
269Both apply only to paths inside the working directory or `additionalDirectories`. In `acceptEdits` mode, Claude Code doesn't auto-approve the request when Claude:
280Both apply to paths inside the working directory or a directory you add. In Python, add one with `add_dirs`, and in TypeScript with `additionalDirectories`. In `acceptEdits` mode, Claude Code doesn't auto-approve the request when Claude:
270281
271282* Works on a path outside that scope
272* Writes to a protected path
283* Writes to a [protected path](https://code.claude.com/docs/en/permission-modes.md#protected-paths)
273284* Removes a path that Claude Code recognizes as a [critical path](https://code.claude.com/docs/en/permission-modes.md#critical-paths) with `rm` or `rmdir`
274285* Runs [`touch`](https://code.claude.com/docs/en/permission-modes#auto-approve-file-edits-with-acceptedits-mode) with, for example, an option, a glob, or a `timeout 5` or `LANG=C` prefix
275286
from line 300
289300
290301If your `PreToolUse` hook returns `allow` for a recognized critical-path removal, a read from a network path, or a call to a tool marked `always_ask`, the call is still denied. The check that recognizes these removals [can miss some commands](https://code.claude.com/docs/en/permission-modes.md#critical-paths).
291302
292**Use when:** you want a fixed, explicit tool surface for a headless agent and prefer a hard deny over silent reliance on `canUseTool` being absent.
303**Use when:** you run a headless agent and want a hard deny for each call that would otherwise prompt.
293304
294305#### Bypass permissions mode (`bypassPermissions`)
295306
from line 310
299310>
300311> Use with extreme caution. Claude has full system access in this mode. Only use in controlled environments where you trust all possible operations.
301312>
302> `allowed_tools` does not constrain this mode. Every tool is approved, not just the ones you listed. These controls still apply:
313> `allowed_tools` doesn't constrain this mode, and calls to tools you didn't list are approved too. These controls still apply:
303314>
304315> * Deny rules, explicit `ask` rules, and hooks are evaluated before the mode check and can still block a tool.
305> * Connector tools [your organization set to `ask`](https://code.claude.com/docs/en/mcp#organization-controls-on-connector-tools), tools that require user interaction, and recognized [critical-path removals](https://code.claude.com/docs/en/permission-modes.md#critical-paths) still fall through to your `canUseTool` callback. The check that recognizes these removals [can miss some commands](https://code.claude.com/docs/en/permission-modes.md#critical-paths), and you can [turn off the critical-path removal prompt](https://code.claude.com/docs/en/permission-modes.md#turn-off-the-critical-path-removal-prompt-in-bypasspermissions-mode). Outside a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md), calls to custom tools your application [marks `always_ask`](https://code.claude.com/docs/en/agent-sdk/custom-tools#require-approval-for-specific-tools) fall through to the callback too.
316> * Connector tools [your organization set to `ask`](https://code.claude.com/docs/en/mcp#organization-controls-on-connector-tools), tools that require user interaction, recognized [critical-path removals](https://code.claude.com/docs/en/permission-modes.md#critical-paths), and Bash commands flagged [`Dangerous rm operation not ruled out`](https://code.claude.com/docs/en/permission-modes#dangerous-rm-operation-not-ruled-out) still fall through to your `canUseTool` callback. The check that recognizes critical-path removals [can miss some commands](https://code.claude.com/docs/en/permission-modes.md#critical-paths), and you can [turn off the critical-path removal prompt](https://code.claude.com/docs/en/permission-modes.md#turn-off-the-critical-path-removal-prompt-in-bypasspermissions-mode). Outside a [cloud session](https://code.claude.com/docs/en/claude-code-on-the-web.md), calls to custom tools your application [marks `always_ask`](https://code.claude.com/docs/en/agent-sdk/custom-tools#require-approval-for-specific-tools) fall through to the callback too.
306317> * The [cross-session messaging safeguards](https://code.claude.com/docs/en/permission-modes.md#skip-all-checks-with-bypasspermissions-mode) still apply.
307318
308319#### Plan mode (`plan`)
309320
310Claude explores the codebase and produces a plan without editing your source files. File edits are never auto-approved in plan mode, even when an allow rule matches or a `PreToolUse` hook returns `allow`. They prompt through your `canUseTool` callback instead.
321Claude explores the codebase and produces a plan. During planning, edits made with Claude's file tools outside [protected paths](https://code.claude.com/docs/en/permission-modes.md#protected-paths) reach your `canUseTool` callback, even when an allow rule matches or a `PreToolUse` hook returns `allow`. [`AskUserQuestion`](https://code.claude.com/docs/en/agent-sdk/user-input#handle-clarifying-questions) calls reach your callback too, even when an allow rule names the tool.
311322
312While auto mode is available to the session, commands Claude runs during planning don't reach your callback by default, because the classifier model that [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) uses [reviews them instead](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode). With that review on, the classifier can also approve read-only calls that would otherwise reach your callback, such as a `WebFetch` call with no allow rule.
323When [auto mode](https://code.claude.com/docs/en/permission-modes.md#eliminate-prompts-with-auto-mode) is available, Claude Code sends these calls during planning to [auto mode's classifier](https://code.claude.com/docs/en/permission-modes.md#analyze-before-you-edit-with-plan-mode) for review instead of to your callback, when no allow rule approves them:
313324
325* Shell commands
326* Web fetches
327* Web searches
328* Calls to MCP tools that their server marks read-only
329
330This review is on by default. To turn it off, set [`useAutoModeDuringPlan`](https://code.claude.com/docs/en/settings-reference#useautomodeduringplan) to `false` in the `settings` option you pass to `query()`, or in your user settings. While the review is off, web searches and calls to MCP tools marked read-only reach your callback.
331
332For shell commands and web fetches, the table shows whether each call reaches your callback:
333
334| Call during planning | Review on | Review off, or auto mode not available |
335| :- | :- | :- |
336| A [read-only](https://code.claude.com/docs/en/permissions.md#read-only-commands) shell command, such as `ls` | Runs without reaching your callback | Runs without reaching your callback |
337| Any other shell command that no allow rule approves, except a [critical-path removal](https://code.claude.com/docs/en/permission-modes.md#critical-paths) | Goes to the classifier, which approves or refuses it without your callback | Reaches your callback |
338| A `WebFetch` call to a [preapproved documentation domain](https://code.claude.com/docs/en/tools-reference.md#webfetch-tool-behavior) | Runs without reaching your callback | Runs without reaching your callback |
339| Any other `WebFetch` call that no allow rule approves | Goes to the classifier, which approves or refuses it without your callback | Reaches your callback |
340
341For what happens after the classifier refuses several calls in a row, see [Repeated-block thresholds](https://code.claude.com/docs/en/permission-modes.md#repeated-block-thresholds).
342
314343> [!NOTE]
315344>
316345> In the TypeScript SDK, if you set `allowDangerouslySkipPermissions: true` alongside `permissionMode: 'plan'`, file edits still reach your `canUseTool` callback. To switch a session that starts in plan mode to `bypassPermissions` later with `setPermissionMode()`, you need `allowDangerouslySkipPermissions` set from the start.
317346
318Claude may use `AskUserQuestion` to clarify requirements before finalizing the plan. See [Handle approvals and user input](https://code.claude.com/docs/en/agent-sdk/user-input.md#handle-clarifying-questions) for handling these prompts.
319
320**Use when:** you want Claude to propose changes without executing them, such as during code review or when you need to approve changes before they're made.
347**Use when:** you want Claude to produce a plan first, such as during code review or before a large change.
321348
322349#### Auto mode (`auto`)
323350
agent-sdk/python Changed · +8 / -3 lines
from line 1171
11711171PermissionMode = Literal[
11721172 "default", # Standard permission behavior
11731173 "acceptEdits", # Auto-accept file edits
1174 "plan", # Planning mode - explore without editing
1174 "plan", # Planning mode - Claude explores and plans
11751175 "dontAsk", # Deny anything not pre-approved instead of prompting
11761176 "bypassPermissions", # Bypass permission checks; explicit ask rules still prompt (use with caution)
11771177 "auto", # A model classifier reviews actions such as shell commands and network requests
from line 1210
12101210
12111211Returns a `PermissionResult` (either `PermissionResultAllow` or `PermissionResultDeny`).
12121212
1213The callback is the SDK replacement for the interactive permission prompt: it's invoked only when the [permission evaluation flow](https://code.claude.com/docs/en/agent-sdk/permissions.md#how-permissions-are-evaluated) resolves to a prompt. Tool calls already approved by an `allowed_tools` entry, a settings allow rule, or the permission mode, such as `acceptEdits` or `bypassPermissions`, never invoke it. To gate every tool call, use a [`PreToolUse` hook](https://code.claude.com/docs/en/agent-sdk/hooks) instead.
1213The callback replaces the interactive permission prompt. The SDK calls `can_use_tool` when the [permission evaluation flow](https://code.claude.com/docs/en/agent-sdk/permissions.md#how-permissions-are-evaluated) resolves to a prompt. Calls approved in either of these ways run without calling `can_use_tool`:
12141214
1215* A call that an `allowed_tools` entry or a settings allow rule approves
1216* A call the permission mode approves, such as a file edit in `acceptEdits` mode
1217
1218To check those calls, use a [`PreToolUse` hook](https://code.claude.com/docs/en/agent-sdk/hooks), which runs for them too.
1219
12151220An allow rule doesn't pre-approve the [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves); see [How permissions are evaluated](https://code.claude.com/docs/en/agent-sdk/permissions.md#how-permissions-are-evaluated) for which of them reach the callback and what happens in `dontAsk` and `auto` mode.
12161221
12171222### `ToolPermissionContext`
from line 3660
36553660
36563661> [!NOTE]
36573662>
3658> The built-in sandbox proxy enforces the network allowlist based on the requested hostname and does not terminate or inspect TLS traffic, so techniques such as [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) can potentially bypass it. See [Sandboxing security limitations](https://code.claude.com/docs/en/sandboxing.md#security-limitations) for details and [Secure deployment](https://code.claude.com/docs/en/agent-sdk/secure-deployment.md#traffic-forwarding) for configuring a TLS-terminating proxy.
3663> The built-in sandbox proxy enforces the network allowlist based on the requested hostname. By default, the proxy doesn't terminate or inspect TLS traffic, so techniques such as [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) can potentially bypass the allowlist. See [Sandboxing security limitations](https://code.claude.com/docs/en/sandboxing.md#security-limitations) for details and [Secure deployment](https://code.claude.com/docs/en/agent-sdk/secure-deployment.md#traffic-forwarding) for configuring a TLS-terminating proxy.
36593664
36603665### `SandboxIgnoreViolations`
36613666
agent-sdk/secure-deployment Changed · +15 / -13 lines
from line 18
1818
1919Claude Code includes several security features that address common concerns. See the [security documentation](https://code.claude.com/docs/en/security.md) for full details.
2020
21* **Permissions system**: Every tool and bash command can be configured to allow, block, or prompt the user for approval. Use glob patterns to create rules like "allow all npm commands" or "block any command with sudo". Organizations can set policies that apply across all users. See [permissions](https://code.claude.com/docs/en/permissions.md).
22* **Command parsing for permissions**: Before executing bash commands, Claude Code parses them into an AST and matches the result against your permission rules. Commands that cannot be parsed cleanly, or that do not match an allow rule, require explicit approval. A small set of constructs such as `eval` always require approval regardless of allow rules. This is a permission gate, not a sandbox; apart from built-in safety checks such as the [critical-path check](https://code.claude.com/docs/en/permission-modes.md#critical-paths) on `rm` and `rmdir` and the [protected paths](https://code.claude.com/docs/en/permission-modes.md#protected-paths) list, it does not infer whether a command is dangerous from its target path or effects.
21* **Permissions system**: Permission rules decide whether a tool call runs, is blocked, or asks for approval first. For the forms a Bash rule misses and how rules combine with permission modes, see [What a Bash rule doesn't match](https://code.claude.com/docs/en/permissions.md#bash-rule-limits) and [Configure permissions](https://code.claude.com/docs/en/agent-sdk/permissions.md). Administrators can also set rules in [managed settings](https://code.claude.com/docs/en/permissions.md#managed-settings).
22* **Critical-path removals**: With the permission mode set to `default`, an `rm` or `rmdir` command recognized as removing your working directory or another [critical path](https://code.claude.com/docs/en/permission-modes.md#critical-paths) needs approval. A matching allow rule doesn't skip that approval. This is a permission gate, not a sandbox. To control what the agent can write, use [filesystem controls](#filesystem-configuration).
2323* **Web search summarization**: Search results are summarized rather than passing raw content directly into the context, reducing the risk of prompt injection from malicious web content.
2424* **Sandbox mode**: Bash commands can run in a sandboxed environment that restricts filesystem and network access. See the [sandboxing documentation](https://code.claude.com/docs/en/sandboxing.md) for details.
2525
from line 79
7979**How it works:**
8080
8181* **Filesystem**: Uses OS primitives (`bubblewrap` on Linux, `sandbox-exec` on macOS) to restrict read/write access to configured paths
82* **Network**: Removes network namespace (Linux) or uses Seatbelt profiles (macOS) to route network traffic through a built-in proxy
82* **Network**: Runs commands in their own network namespace (Linux) or under a Seatbelt profile (macOS) and routes their traffic through a built-in proxy that allows the configured domains. A connection to an outside host that skips the proxy fails.
8383* **Configuration**: JSON-based allowlists for domains and filesystem paths
8484
8585**Setup:**
8686
87```bash theme={null}
88npm install @anthropic-ai/sandbox-runtime
89```
87For the install, configuration, and launch steps, see [Set up and launch the runtime](https://code.claude.com/docs/en/sandbox-environments.md#set-up-and-launch-the-runtime).
9088
91Then create a configuration file specifying allowed paths and domains.
92
9389**Security considerations:**
9490
95911. **Same-host kernel**: Unlike VMs, sandboxed processes share the host kernel. A kernel vulnerability could theoretically enable escape. For some threat models this is acceptable, but if you need kernel-level isolation, use gVisor or a separate VM.
9692
972. **No TLS inspection**: The proxy allowlists domains based on the client-supplied hostname and does not terminate or inspect encrypted traffic. Code running inside the sandbox can potentially use [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) or similar techniques to reach hosts outside the allowlist. If your threat model requires stronger guarantees, configure a [TLS-terminating proxy](#traffic-forwarding). See the [sandboxing security limitations](https://code.claude.com/docs/en/sandboxing.md#security-limitations) for more detail. Separately, if the agent has permissive credentials for an allowed domain, ensure it cannot use that domain to trigger other network requests or to exfiltrate data.
932. **No TLS inspection**: By default, the proxy allowlists domains based on the client-supplied hostname and doesn't terminate or inspect encrypted traffic. Code running inside the sandbox can potentially use [domain fronting](https://en.wikipedia.org/wiki/Domain_fronting) or similar techniques to reach hosts outside the allowlist. If your threat model requires stronger guarantees, use a TLS-terminating proxy that inspects traffic, as [Traffic forwarding](#traffic-forwarding) describes. For more information, see the [sandboxing security limitations](https://code.claude.com/docs/en/sandboxing.md#security-limitations).
9894
953. **Credentials for allowed domains**: If the agent has permissive credentials for an allowed domain, ensure it cannot use that domain to trigger other network requests or to exfiltrate data.
96
9997For many single-developer and CI/CD use cases, sandbox-runtime raises the bar significantly with minimal setup. The sections below cover containers and VMs for deployments requiring stronger isolation.
10098
10199### Containers
from line 129
131129| `--security-opt seccomp=...` | Restricts available syscalls; Docker's default blocks \~44, custom profiles can block more |
132130| `--read-only` | Makes the container's root filesystem immutable, preventing the agent from persisting changes |
133131| `--tmpfs /tmp:...` | Provides a writable temporary directory that's cleared when the container stops |
134| `--network none` | Removes all network interfaces; the agent communicates through the mounted Unix socket below |
132| `--network none` | Cuts the container off from external networks |
135133| `--memory 2g` | Limits memory usage to prevent resource exhaustion |
136134| `--pids-limit 100` | Limits process count to prevent fork bombs |
137135| `--user 1000:1000` | Runs as a non-root user |
from line 138
140138
141139**Unix socket architecture:**
142140
143With `--network none`, the container has no network interfaces at all. The only way for the agent to reach the outside world is through the mounted Unix socket, which connects to a proxy running on the host. This proxy can enforce domain allowlists, inject credentials, and log all traffic.
141With `--network none`, a DNS lookup or a direct connection to another host fails inside the container. To let code in the container reach other hosts, run a proxy on the host and mount its Unix socket into the container. If you point `ANTHROPIC_BASE_URL` or `HTTP_PROXY` at a port on `localhost`, as [Configuring Claude Code to use a proxy](#configuring-claude-code-to-use-a-proxy) shows, relay that port inside the container to the socket.
144142
145This is the same architecture used by [sandbox-runtime](https://github.com/anthropics/sandbox-runtime). Even if the agent is compromised via prompt injection, it cannot exfiltrate data to arbitrary servers. It can only communicate through the proxy, which controls what domains are reachable. For more details, see the [Claude Code sandboxing blog post](https://www.anthropic.com/engineering/claude-code-sandboxing).
143You can set up this proxy to enforce domain allowlists, inject credentials, and log all traffic.
144
145> [!WARNING]
146>
147> Within your proxy's allowlist, the agent can send data to any allowed domain. Allow only the domains the agent needs.
146148
147149**Additional hardening options:**
148150
agent-sdk/typescript Changed · +8 / -3 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
from line 1336
13361336 | "default" // Standard permission behavior
13371337 | "acceptEdits" // Auto-accept file edits
13381338 | "bypassPermissions" // Bypass permission checks; explicit ask rules still prompt
1339 | "plan" // Planning mode - explore without editing
1339 | "plan" // Planning mode - Claude explores and plans
13401340 | "dontAsk" // Don't prompt for permissions, deny if not pre-approved
13411341 | "auto"; // A model classifier reviews actions such as shell commands and network requests
13421342```
from line 1345
13451345
13461346Custom permission function type for controlling tool usage.
13471347
1348The function is the SDK replacement for the interactive permission prompt: it's invoked only when the [permission evaluation flow](https://code.claude.com/docs/en/agent-sdk/permissions.md#how-permissions-are-evaluated) resolves to a prompt. Tool calls already approved by an `allowedTools` entry, a settings allow rule, or the permission mode, such as `acceptEdits` or `bypassPermissions`, never invoke it. To gate every tool call, use a [`PreToolUse` hook](https://code.claude.com/docs/en/agent-sdk/hooks) instead.
1348The function replaces the interactive permission prompt. The SDK calls `canUseTool` when the [permission evaluation flow](https://code.claude.com/docs/en/agent-sdk/permissions.md#how-permissions-are-evaluated) resolves to a prompt. Calls approved in either of these ways run without calling `canUseTool`:
13491349
1350* A call that an `allowedTools` entry or a settings allow rule approves
1351* A call the permission mode approves, such as a file edit in `acceptEdits` mode
1352
1353To check those calls, use a [`PreToolUse` hook](https://code.claude.com/docs/en/agent-sdk/hooks), which runs for them too.
1354
13501355An allow rule doesn't pre-approve the [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves); see [How permissions are evaluated](https://code.claude.com/docs/en/agent-sdk/permissions.md#how-permissions-are-evaluated) for which of them reach the callback and what happens in `dontAsk` and `auto` mode.
13511356
13521357```typescript theme={null}
from line 4795
47904795**Tool name:** `PushNotification`
47914796
47924797```typescript theme={null}
4793type PushNotificationOutput = {
4794 message: string;
4795 pushSent?: boolean;
4796 localSe
4798type PushNoti
agent-sdk/user-input Changed · +4 / -4 lines
from line 43
4343The callback fires in two cases:
4444
45451. **Tool needs approval**: Claude wants to use a tool that isn't auto-approved by a [permission rule](https://code.claude.com/docs/en/agent-sdk/permissions.md) or permission mode. Check `tool_name` for the tool (e.g., `"Bash"`, `"Write"`).
462. **Claude asks a question**: Claude calls the `AskUserQuestion` tool. Check if `tool_name == "AskUserQuestion"` to handle it differently. If you specify a `tools` array, include `AskUserQuestion` for this to work. See [Handle clarifying questions](#handle-clarifying-questions) for details.
462. **Claude asks a question**: Claude calls the `AskUserQuestion` tool. Check if `tool_name == "AskUserQuestion"` to handle it differently. If you specify a `tools` array, include `AskUserQuestion` for this to work. For more information, see [Handle clarifying questions](#handle-clarifying-questions).
4747
4848> [!WARNING]
4949>
50> **The callback never fires for auto-approved tools.** Any approval earlier in the [permission evaluation flow](https://code.claude.com/docs/en/agent-sdk/permissions.md#how-permissions-are-evaluated), an allow rule or a mode like `acceptEdits` or `bypassPermissions`, resolves the call before `canUseTool` is consulted. If you list a tool bare in `allowed_tools`, a `canUseTool` check for that tool runs only when the [evaluation flow](https://code.claude.com/docs/en/agent-sdk/permissions.md#how-permissions-are-evaluated) routes the call back to a prompt, such as an ask rule or `plan` mode. For logic that must apply to every tool call, use a [`PreToolUse` hook](https://code.claude.com/docs/en/agent-sdk/hooks), which executes before the rest of the flow and can allow, deny, or modify requests.
50> **An earlier step can allow or deny a call before `canUseTool` runs.** The [permission evaluation flow](https://code.claude.com/docs/en/agent-sdk/permissions.md#how-permissions-are-evaluated) checks deny rules, the permission mode, and allow rules before your callback.
5151>
52> An allow rule doesn't pre-approve the [actions no mode auto-approves](https://code.claude.com/docs/en/permission-modes.md#actions-no-mode-auto-approves); see [How permissions are evaluated](https://code.claude.com/docs/en/agent-sdk/permissions.md#how-permissions-are-evaluated) for which of them reach the callback and what happens in `dontAsk` and `auto` mode.
52> To run your checks on calls that a rule or the permission mode already allowed, use a [`PreToolUse` hook](https://code.claude.com/docs/en/agent-sdk/hooks), which runs for those calls and can allow, deny, or modify them.
5353
5454You can also use the [`PermissionRequest` hook](https://code.claude.com/docs/en/agent-sdk/hooks#available-hooks) to send external notifications (Slack, email, push) when Claude is waiting for approval.
5555
desktop Changed · +5 / -4 lines
from line 1285
12851285
12861286> [!WARNING]
12871287>
1288> If you sign in to Desktop with a Claude account, don't count on a task to run overnight. Desktop renews that sign-in for the task only while Desktop is running and connected, so the task's sign-in can expire after you disconnect, and the task then stops. How much time is left when you disconnect varies, and it can be only a few minutes.
1288> If you sign in to Desktop with a Claude account, don't count on a task to run overnight. Desktop renews that sign-in for the task only while Desktop is running, connected, and signed in, so the task's sign-in can expire after you disconnect, and the task then stops. How much time is left when you disconnect varies, and it can be only a few minutes.
12891289>
12901290> The work done so far stays on the remote machine, and you can continue with a message when you return.
12911291>
12921292> If the task must run through the night:
12931293>
1294> * [Keep your computer awake](https://code.claude.com/docs/en/desktop-scheduled-tasks.md#how-scheduled-tasks-run) and online, with the lid open and Desktop running
1294> * [Keep your computer awake](https://code.claude.com/docs/en/desktop-scheduled-tasks.md#how-scheduled-tasks-run) and online, with the lid open and Desktop running and signed in
12951295> * Use a login that works without a prompt, such as a key that your SSH agent holds, for the remote machine and for any jump host on the way. Desktop can then reconnect on its own after a drop.
12961296>
12971297> For a task that must run while your computer is asleep or off, start a [cloud session](#run-long-running-tasks-in-the-cloud) instead.
from line 1299
12991299* **After sleep or a network loss**: you get the running task back if the process [still runs](#limits-while-desktop-is-disconnected) and Desktop can log in without a prompt. If it can't, [send a message](#reconnect-after-sleep-or-a-network-loss).
13001300* **After a quit**: the task keeps running, but you lose it when the session opens again unless Desktop can rejoin its process. Check [when Desktop can rejoin](#reopen-a-session-after-you-quit-desktop) before you quit. If you lost the task, send a message to continue.
13011301
1302When you come back and the task isn't done, check for word that Desktop can't reconnect, an authentication error, or a waiting request:
1302When you come back and the task isn't done, check for Desktop's sign-in page, word that Desktop can't reconnect, an authentication error, or a waiting request:
13031303
1304* **Sign-in page**: sign in. If the task stopped, send a message to continue. On an Enterprise plan, your organization can [sign you out a set number of days after you sign in](https://support.claude.com/en/articles/13163631-configuring-session-security-settings), however active you are. With a Claude account, Desktop doesn't renew the task's sign-in while you're signed out, so the task can stop.
13041305* **Desktop can't reconnect**: the session says why, and a notification may say so too. Desktop may [need you to log in](#reconnect-after-sleep-or-a-network-loss).
13051306* **Authentication error**: the [sign-in token or credential](#limits-while-desktop-is-disconnected) may have expired. With a Claude account, send a message to continue. With a third-party provider, see [SSH remote sessions in Claude Desktop on 3P](https://claude.com/docs/third-party/claude-desktop/ssh-remote-sessions).
13061307* **Waiting request**: [answer it](#handle-requests-that-arrive-while-you-are-away)
agent-view Changed · +2 / -2 lines
from line 1016
10161016
10171017On macOS, the background session host runs as its own process and requests access to protected folders separately from your terminal. If a background session reports `Operation not permitted` when reading `~/Desktop`, `~/Documents`, `~/Downloads`, or another protected location, grant access in System Settings under Privacy & Security > Files and Folders, or enable Full Disk Access for the entry.
10181018
1019With the native installer, the entry appears as Claude Code and the grant persists across updates. With other install methods such as Homebrew or npm, the entry shows the binary path and may need to be granted again after updating.
1019In either list, look for an entry named Claude Code, or one named for the path or file name of the `claude` binary. That file name can be a version number such as `2.1.316`. If `Operation not permitted` returns after Claude Code updates, look for a new entry, such as one named for the new version. If one is there, grant it access.
10201020
10211021### Background sessions can't reach local-network hosts on macOS
10221022
from line 1063
10631063| v2.1.296 | A prompt or `!` shell command that you enter [as the session moves to the background](#switch-sessions-without-leaving-the-terminal) is stopped or left unsent, and its text is kept in prompt history. Before this release, the response or command kept running where you could no longer see it, and a prompt sent right after `←` could run a second time unseen. A prompt typed while `SessionStart` hooks were still running was lost: not sent, and not in prompt history. |
10641064| v2.1.295 | `Ctrl+C` at the idle prompt of an [attached background session](#attach-to-a-session) leaves the pending wakeup of a [self-paced `/loop`](https://code.claude.com/docs/en/scheduled-tasks#let-claude-choose-the-interval) alone, so pressing it twice detaches and the loop keeps running. `Esc` at that prompt [stops the self-paced loop](https://code.claude.com/docs/en/scheduled-tasks.md#stop-a-loop) and shows a `Pending wakeup cancelled` notice. Before this release, the first `Ctrl+C` could end a self-paced loop without saying so, and `Esc` didn't stop one that had moved to the background with the session. |
10651065| v2.1.295 | On macOS and Linux, when `claude agents` exits while no [supervisor](#keep-sessions-running-after-the-supervisor-stops) is running, it doesn't start a new one on its own. Running sessions then stop about a minute later unless you run `claude agents` again, and agent view can print a notice saying so as it exits. Before this release, the exiting `claude agents` started a new supervisor. |
1066| v2.1.295 | On macOS with the native installer, background sessions that restart together after an update run under the same Claude Code entry that holds the [protected-folder access](#background-sessions-can’t-read-desktop-documents-or-downloads-on-macos) you granted. Before this release, those sessions could run under the binary's own path instead. macOS lists that path as a separate entry, so the folder-access prompts could come back after an update. |
1066| v2.1.295 | On macOS with the native installer, background sessions that restart together after an update run their host processes from the same `~/.local/share/claude/ClaudeCode.app` folder. Before this release, those processes could run from the binary's own path instead. macOS can list that path as a separate entry, so the [folder-access prompts](#background-sessions-can’t-read-desktop-documents-or-downloads-on-macos) could come back after an update. |
10671067| v2.1.290 | [`claude attach` and `claude logs`](#manage-sessions-from-the-shell) can take part of a session's name in place of the ID. |
10681068| v2.1.290 | `/model`, `/effort`, `/rename`, and `/usage` sent as a [peek reply](#peek-and-reply) to a working session run right away. |
10691069| v2.1.290 | A [peek reply](#peek-and-reply) that can't be delivered is no longer saved for the next restart when it starts with `/`, or when it answers a question with predefined choices while the session's process is running. |
claude-tag Changed · +1 / -1 lines
This page is larger than the 256 KiB this site keeps, so one side of the diff below stops where the stored text does.
Nothing in the body moved in this read. What changed is above.