scope-lock

PreToolUse hook for Claude Code that enforces filesystem permissions per project. Define which files the agent can read and write in a manifest — everything else is denied.

Install

npm install -g scope-lock

Setup

1. Create .scope-lock.json in your project root:

{
  "allow": {
    "read": ["src/**", "package.json", "README.md", "tsconfig.json", "*.config.*"],
    "write": ["src/**"]
  },
  "deny": [".env*", "node_modules/**", ".git/**", "**/secrets/**"]
}

2. Add to ~/.claude/settings.json:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Read|Write|Edit|Glob|Grep|Bash",
        "hooks": [
          {
            "type": "command",
            "command": "scope-lock",
            "timeout": 5
          }
        ]
      }
    ]
  }
}

How It Works

1. Claude wants to call a tool (Read, Write, Edit, Bash, etc.)
2. The hook intercepts the call and extracts file paths from the tool input
3. Paths are matched against your manifest's allow/deny rules
4. Deny rules take precedence over allow rules
5. Paths matching no rule are denied by default
6. Exit 0 = allow, Exit 2 = deny with reason

Manifest Format

Supports both .scope-lock.json and .scope-lock.yaml:

JSON:

{
  "allow": {
    "read": ["src/**", "docs/**", "*.md"],
    "write": ["src/**"]
  },
  "deny": [".env*", ".git/**", "node_modules/**"]
}

YAML:

allow:
  read:
    - src/**
    - docs/**
    - "*.md"
  write:
    - src/**
deny:
  - .env*
  - .git/**
  - node_modules/**

Glob Patterns

• * — matches any characters except /
• ** — matches any characters including / (recursive)
• ? — matches a single character
• .env* — matches .env, .env.local, .env.production
• src/** — matches everything under src/

Tool Path Extraction

| Tool | Path Source | |------|------------| | Read, Write, Edit | tool_input.file_path | | Glob | tool_input.path (default: .) | | Grep | tool_input.path (default: .) | | Bash | Best-effort regex extraction from command |

Requirements

• Node.js >= 22
• ESM only

License

MIT