The permission prompt

The box that appears before a file is written is not a formality. It 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 prompt is really asking

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.

Lesson 16 is about writing those rules yourself, in a file, which is the same thing without the clicking.

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 sessions on paid plans, 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 are lesson 6, 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.

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.

PreviousHow it finds things

This is what real progress feels like.