# PreToolUse read-only hook

> Plan mode's read-only promise is prompt reinforcement, not a lockdown. A PreToolUse hook blocking Write and Edit in plan mode makes it actually read-only.

URL: https://bartlomiejkrupa.dev/notes/pre-tool-use-read-only-hook/
Category: snippet | Updated: 2026-10-07
Summary: Plan mode's read-only promise is prompt reinforcement, not a lockdown. A PreToolUse hook blocking Write and Edit in plan mode makes it actually read-only.

Plan mode *feels* read-only. Claude Code now blocks its edit tools until you approve a plan, but two gaps remain: sessions with bypass permissions available skip that block, and shell commands still run while planning. The instructions themselves are a short injected prompt - "MUST NOT make any edits" (Armin Ronacher, 2025-12-17) - and a March 2026 write-up got Claude to modify a `.zshrc` in plan mode. Writing MUST NOT in all caps is not a security boundary.

## Make it actually read-only

Wire a `PreToolUse` hook that denies `Write` and `Edit` when `permission_mode` is `plan`, with one exception for the plan file under `~/.claude/plans/`:

```json
{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|NotebookEdit",
        "hooks": [
          {
            "type": "command",
            "command": "~/.claude/hooks/block-plan-writes.sh"
          }
        ]
      }
    ]
  }
}
```

The script reads the hook payload on stdin and exits with code 2 (blocking the call - exit code 1 is a non-blocking error) when the condition matches. This costs nothing in capability: the agent never legitimately writes anywhere else while planning.

For untrusted repos or unattended runs, climb the [sandbox ladder](/notes/sandbox-ladder) instead. Decision tree for when to use plan mode: [Plan mode decision tree](/notes/plan-mode-decision-tree). Full article: [Claude Code plan mode](/articles/claude-code-plan-mode).

Sources:
- Hooks reference: https://code.claude.com/docs/en/hooks
- Choose a permission mode: https://code.claude.com/docs/en/permission-modes
- What is plan mode?: https://lucumr.pocoo.org/2025/12/17/what-is-plan-mode/
- Claude Code's plan mode isn't read-only: https://blog.sondera.ai/p/claude-codes-plan-mode-isnt-read
