Permissions

Permissions are the checks Claude Code makes before any action that changes the world, asking whether it may write a file, run a command or reach the network.

Last updated: 28 Sep, 2026 · Claude Code

The box that appears before a file is written is the moment the tool asks whether it may act, and understanding it is what makes unattended work possible later.

Reading is free. Searching and reading files happen without asking, because neither one changes anything. The question arrives when a tool would touch the world: writing a file, running a command, reaching the network.

A refusal, captured

The easiest way to see the boundary is to ask for a change without granting anything. Here it is asked to create a README in a directory where it has no write permission.

bash

claude -p "Create a file called README.md containing exactly one line: # Link shortener" \
  --output-format json

Captured from a real run

is_error: False   turns: 2   cost: $0.0089
result: Waiting for write permission to create README.md.
permission_denials: [{"tool_name": "Write",
                      "tool_input": {"file_path": "/tmp/linkshort/README.md",
                                     "content": "# Link shortener\n"}}]

Three things in that output are worth reading twice. The run did not fail, it finished and told you what it wanted. The denial is reported as data, with the exact tool and the exact arguments it was going to use. And the file was not created.

That shape is what makes the tool safe to automate. A blocked action is a fact you can read, not an exception in a log somewhere.

What the permission prompt asks

When the same thing happens in the interactive session, you get a choice rather than a denial: allow this once, allow this kind of thing from now on, or refuse. The middle option is the interesting one, because it writes a rule into your settings, and that rule is what stops you being asked about npm test forty times a day.

The settings.json lesson is about writing those rules yourself, in a file, which is the same thing without the clicking.

In VS Code

The same question arrives as a diff of the proposed edit next to your file, with buttons to accept or reject it. In Manual mode you can also go through a large edit one change at a time with Claude Code: Accept Change at Cursor and Reject Change at Cursor from the Command Palette.

What happens before a tool acts

Hover or tap a piece to see what it is and which lesson built it.

Trace a request

Pick one to watch it run, step by step.

Modes, in one paragraph

How often you are asked is set by a permission mode, and you cycle through them with Shift+Tab. Manual asks before edits and commands. Accept edits stops asking about file edits and common filesystem commands. Plan lets it look but not change anything. Auto, the starting mode for interactive terminal and VS Code sessions in current versions, has a classifier review actions in the background and block the risky ones instead of asking you.

Each of those gets a lesson of its own in part 4. For now the useful thing is knowing the dial exists and that it is one keystroke away.

Permission is not undo

Permissions cover what it may do. They do not undo what it did. File edits are reversible through checkpoints, which the rewind and checkpoints lesson covers, but a command that emailed a customer or dropped a table is not something any checkpoint can take back. That distinction decides which mode you should be in.

Previous: Codebase search
Next: Plan mode
Reference: Claude Code docs

Try it yourself

Run the README command above in a scratch directory and read the JSON it prints.
Start a session, ask for an edit, and read the prompt properly before answering it.

PreviousCodebase search

This is what real progress feels like.