skip to content

Agent Loop & Safeguards

A gather-act-verify loop over built-in tools, fenced by allow, ask and deny rules, permission modes and file checkpoints. Asked because autonomy and safety are set here, not in the prompt.

part ofClaude Coderead it →
on this pageshow

explore

questions

21

After Claude Code deleted a failing test's assertions with Edit to make it pass, how do you rewind and which restore option fits?

level: juniorimportance: must knowfreq 30%

answer

  1. a checkpoint before every prompt
  2. two presses on an empty input
  3. /rewind and its two aliases
  4. code, conversation, or both
  5. rewind beats arguing in-thread

basics

~20 s

Press Esc twice on an empty prompt, or run /rewind, pick the prompt that started the bad turn, and choose Restore code and conversation: the files and the conversation both return to before that prompt.

solid answer

~40 s

Claude Code takes a checkpoint before every prompt that starts a turn. With the prompt input empty, pressing `Esc` twice opens the rewind menu; `/rewind` (aliases `/checkpoint` and `/undo`) opens the same menu. I pick the prompt that started the bad turn and choose **Restore code and conversation**, so the deleted assertions come back and the bad attempt leaves the context. The original prompt returns to the input, and I re-send it with the missing constraint: fix the code, never weaken the test. **Restore code** alone reverts files and keeps the conversation; **Restore conversation** alone keeps the current code. Rewinding usually beats correcting in-thread, because a wrong attempt left in context tends to anchor later answers.

go deeper

for a junior

Recall that a checkpoint exists before every prompt, that Esc twice on an empty input or /rewind opens the menu, and the three restore choices.

for a middle

Explain what each restore option does to files and to context, why the code options can be missing, and why the restored prompt reappears in the input.

for a senior

Show judgement: rewind and re-prompt with the missing constraint rather than arguing with a wrong attempt that keeps anchoring the session.

for a principal

Frame rewind as a cheap, local undo for one developer's session and say what the team still relies on for durable recovery and review.

## What a checkpoint is Claude Code **checkpoints** the state of your code automatically. Every prompt you send that starts a turn creates a new checkpoint, and before Claude changes a file with one of its file-editing tools (such as `Edit` or `Write`), Claude Code snapshots that file's current contents. You never create a checkpoint by hand; you only choose one to go back to. That makes the scenario in the question cheap to undo. The agent "fixed" a failing test by deleting its assertions, and it did so with `Edit`, a tracked file-editing tool, so the pre-edit contents of the test file are in the snapshot for the checkpoint taken before that prompt. A few properties make checkpoints dependable for this kind of slip: - **Automatic.** Nothing to remember to save; the checkpoint exists before the prompt runs. - **Persistent across resume.** Checkpoints are saved with the conversation, so `/rewind` still works after you resume the session later. - **Bounded.** File snapshots are kept for the 100 most recent checkpoints in a session, which covers the usual "undo the last few turns" case. - **Separate from git.** Rewinding does not touch commits, branches or the index; it rewrites the working-tree files it snapshotted. ## Opening the rewind menu There are two ways in, and both open the same menu: - **`Esc` twice** while the prompt input is empty. If the input holds text, the double press clears the draft instead and saves it to input history, so `Up` recalls it later. - **`/rewind`**, which also answers to the aliases `/checkpoint` and `/undo`. The menu lists each prompt you sent in the session. A message you typed while Claude was working that joined the running turn gets no checkpoint of its own and is not listed; to undo what came after it, you rewind to the prompt that started that turn. ## The actions, side by side After selecting a prompt you choose what to do with it: | Action | Files on disk | Conversation | | - | - | - | | **Restore code and conversation** | Reverted to the checkpoint | Rewound to that message | | **Restore conversation** | Kept as they are now | Rewound to that message | | **Restore code** | Reverted to the checkpoint | Kept as it is now | | **Summarize from here / up to here** | Unchanged | Part of it compressed into a summary | | **Never mind** | Unchanged | Unchanged | The two code options appear only when the selected checkpoint has tracked file changes to revert; otherwise the menu offers only **Restore conversation**, the summarize options and **Never mind**. After restoring the conversation, the original prompt of the selected message is placed back in the input field so you can edit and re-send it. ## Choosing the option for this case 1. Open the menu and select the prompt that asked Claude to make the test pass. 2. Choose **Restore code and conversation**. The assertions come back, and the turn in which Claude decided deletion was a fix disappears from the context. 3. Edit the restored prompt to add the constraint that was missing, for example that tests are the specification and may not be changed, and send it. The other two options fit other situations: - **Restore code** when the files went wrong but the discussion is worth keeping, for instance when Claude explored the code and found the real cause before taking the shortcut. You then tell it what to do instead, and it still has what it learned. - **Restore conversation** when the code is fine but the conversation drifted, for example after a long tangent you do not want steering the next answers. ## Why rewind instead of replying The tempting move is to type "don't delete tests, put them back". That works sometimes, but the failed attempt stays in the context and can anchor later answers to it, so Claude Code's own guidance is that rewinding usually works better than correcting in the thread. Rewinding also reverts the files mechanically instead of asking the model to reconstruct what it removed. ## Where this stops working Rewind restores only what the file-editing tools changed. Had the agent removed the whole test file with `rm` through `Bash`, a code restore would not bring it back, because changes made by shell commands are not tracked; that boundary, and the other things checkpoints miss, deserve their own discussion. Checkpoints are also session-level recovery, not history: they are kept alongside version control, never instead of it.

  • You press Esc twice in Claude Code and your half-typed prompt vanishes instead of the rewind menu opening. What happened?
    Double `Esc` opens the rewind menu only when the prompt input is empty. With text in the input it clears the draft instead and saves it to input history. Press `Esc` twice again on the now-empty input to open the menu, and press `Up` afterwards to recall the cleared draft.
  • In Claude Code's rewind menu, why might Restore code be missing for the prompt you selected?
    The two code restore options appear only when the selected checkpoint has tracked file changes to revert. If no file edits were captured after that point, for example because the turn only read files or changed them through `Bash`, the menu offers just **Restore conversation**, the summarize options and **Never mind**.

  • Claude Code only checkpoints when you run a save or commit command
  • Pressing Esc twice always opens the rewind menu, even with text typed
  • Restore conversation also reverts the files Claude edited
  • The best fix is replying with corrections and leaving the bad turn in context
  • Rewinding a turn deletes the whole session and starts a new one
open as a page

In Claude Code, what does plan mode let Claude do, how do you enter it, and what happens when you approve the plan?

level: juniorimportance: must knowfreq 34%

basics

~20 s

Plan mode lets Claude read files and run exploratory commands to propose a change without editing source. Enter it with Shift+Tab, a /plan prefix or --permission-mode plan; approving the plan exits plan mode into the mode the chosen option names.

open as a page

In Claude Code, what happens in the gather-context, take-action and verify-results phases, and how do you steer the loop mid-run?

level: juniorimportance: must knowfreq 28%

basics

~20 s

Claude Code repeats three blended phases until the task looks done: gather context (read, search), take action (edit, run commands) and verify results (tests, builds). Each tool result shapes the next step; Esc stops the running call so you can redirect.

open as a page

Claude Code renamed a symbol across the repo with sed through Bash — why can't /rewind undo it, and what else escapes its checkpoints?

level: middleimportance: must knowfreq 22%

basics

~20 s

Checkpoints snapshot only files changed by Claude Code's file-editing tools, so a sed rename through Bash is not tracked. Manual or other-session edits (normally), most subagent edits, symlinked or hard-linked files and remote side effects also escape; use git.

open as a page

In Claude Code, which permission mode fits a supervised refactor, an unattended overnight task and a read-only audit, and why?

level: middleimportance: must knowfreq 30%

basics

~20 s

Use acceptEdits for a supervised refactor you review by diff, plan for a read-only audit since edits stay blocked, and auto for an overnight task; bypassPermissions belongs only in an isolated container or VM, and deny rules hold in every mode.

open as a page

In Claude Code's Manual permission mode, which built-in tools run without asking and which prompt first, and why do their exact names matter?

level: middleimportance: must knowfreq 18%

basics

~20 s

In Manual mode, Read, the search tools, LSP, Agent and AskUserQuestion run without a prompt inside the working directory; Edit, Write, Bash beyond its read-only commands, WebFetch, WebSearch and Skill ask. The names are the strings rules and hook matchers use.

open as a page

In a Claude Code project, which permission rules let `npm run` scripts run without a prompt while blocking Claude from reading `.env` files?

level: middleimportance: must knowfreq 30%

basics

~10 s

Add Bash(npm run ) to permissions.allow and Read(./.env) plus Read(./.env.) to permissions.deny; deny is evaluated first, but it guards Claude's own tools and recognised commands, not a script that opens the file itself.

open as a page

A Claude Code settings file denies `Bash(aws *)` and allows `Bash(aws s3 ls)` — what happens when Claude runs `aws s3 ls`, and why?

level: seniorimportance: must knowfreq 22%

basics

~20 s

The call is blocked: Claude Code checks deny rules, then ask, then allow, and the first match decides regardless of specificity, so an allow rule can never carve an exception out of a matching deny.

open as a page

When you pick 'Yes, and don't ask again' on a Claude Code permission prompt, where is that approval saved and how long does it last?

level: juniorimportance: should knowfreq 16%

basics

~20 s

For Bash commands and WebFetch domains it is saved permanently as an allow rule in .claude/settings.local.json at the git repository root (since v2.1.211); a file-edit approval is never saved and lasts only until the session ends.

open as a page

Since Claude Code v2.1.283, what decides the permission mode a new interactive session starts in, and how does Shift+Tab cycle from there?

level: middleimportance: should knowfreq 14%

basics

~20 s

The --permission-mode flag wins, then permissions.defaultMode from settings, then the built-in default, which is auto for interactive terminal and VS Code sessions since v2.1.283. Shift+Tab goes auto to Manual, then Manual, acceptEdits, plan, with enabled bypass and auto after plan.

open as a page

Why does Claude Code's Edit tool reject an edit whose old_string looks right, and what makes the retry succeed?

level: middleimportance: should knowfreq 12%

basics

~20 s

Edit is exact string replacement: old_string must match the file character for character, including whitespace, and occur exactly once. A retry succeeds after re-reading the file, copying the text exactly, and adding surrounding lines or setting replace_all for repeats.

open as a page

Resuming a five-week-old Claude Code session, /rewind still lists its checkpoints but Restore code fails with 'No files were restored' — why, and what does that say about checkpoints?

level: seniorimportance: should knowfreq 8%

basics

~20 s

Checkpoints are saved with the conversation, but their file backups are deleted by the retention sweep, by default about 30 days (cleanupPeriodDays) after the session last saved one. Checkpoints are short-lived, local session recovery, not version control.

open as a page

In Claude Code's auto mode, what does the background classifier review, what still prompts or is blocked, and when does auto mode fall back to prompting?

level: seniorimportance: should knowfreq 16%

basics

~20 s

A separate classifier model reviews actions other than reads and working-directory edits, blocking escalation and unrecognised infrastructure. Ask rules still prompt, deny rules still block, and 3 blocks in a row or 20 in total revert to prompting.

open as a page

Why won't Claude Code auto-approve writes to .git, .claude or .bashrc, even in acceptEdits with an Edit(.claude/**) allow rule?

level: seniorimportance: should knowfreq 9%

basics

~20 s

Those are protected paths: writes to them are never auto-approved, outside bypassPermissions, because they hold repository state, shell startup files and Claude's own configuration. The check runs before allow rules from settings, so Edit(.claude/**) changes nothing.

open as a page

Why is a Claude Code deny rule such as `Bash(git push *)` not a security boundary, and which commands does it actually stop?

level: seniorimportance: should knowfreq 14%

basics

~20 s

A Bash rule matches the command text Claude writes, after splitting compound commands and stripping a fixed set of wrappers; it stops git push origin main but not git -C . push, git 'push' or the same push inside sh -c.

open as a page

In Claude Code's rewind menu, how do Summarize from here and Summarize up to here differ, and what does neither one change?

level: middleimportance: nice to knowfreq 10%

basics

~10 s

Summarize from here compresses the selected message and everything after it; Summarize up to here compresses everything before it and keeps later messages intact. Neither changes files on disk or deletes the transcript.

open as a page

When you resume a Claude Code session with claude --continue, which permission mode does it start in if it ended in plan or bypassPermissions?

level: middleimportance: nice to knowfreq 6%

basics

~10 s

claude --continue normally restores the mode the session ended in, but not plan or bypassPermissions: both start in the mode a new session would start in. Pass --permission-mode or --dangerously-skip-permissions to choose explicitly.

open as a page

In Claude Code, how do WebFetch and WebSearch differ, and why can WebFetch report that a page lacks something it actually contains?

level: middleimportance: nice to knowfreq 5%

basics

~20 s

WebSearch returns result titles and URLs; WebFetch fetches one URL, converts HTML to Markdown and usually runs an extraction prompt over it in a separate model call. That extraction is lossy, so a missing detail may only mean the prompt never asked.

open as a page

How do Claude Code permission rules name a web domain and an MCP server's tools, and where may wildcards appear in each?

level: middleimportance: nice to knowfreq 8%

basics

~10 s

Web fetches use WebFetch(domain:host), where *.example.com covers subdomains but not example.com itself; MCP tools use mcp__server or mcp__server__tool, and an allow glob must follow a literal mcp__server__ prefix.

open as a page

In Claude Code on macOS or Linux, why do code searches show up as Bash calls rather than Grep or Glob, and what does that change?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

On macOS, Linux and WSL, Glob and Grep are absent from the default tool set; Claude searches with find and grep through Bash, backed by embedded bfs and ugrep. Hooks and permission rules therefore see Bash calls, not Grep or Glob.

open as a page

In Claude Code Read and Edit permission rules, what do the `//`, `~/`, `/` and `./` path prefixes each anchor to?

level: seniorimportance: nice to knowfreq 7%

basics

~20 s

//path is absolute from the filesystem root, ~/path starts at your home directory, /path is relative to the settings source (the project for project settings, ~/.claude for user settings), and path or ./path is relative to the current directory.

open as a page