---
name: ck-privacy-guard
description: Blocks access to sensitive files and ignored directories. HARD-GATE on .env files, credentials, secrets, API keys. Also enforces .ckignore directory exclusions. Activates automatically on every file read and directory access attempt.
---

# ck-privacy-guard

Automatic guard that blocks access to sensitive files and ignored directories. Runs on every file read and bash command — never invoked manually.

## When Active

- **Privacy Block**: Fires before any file read (`Read` tool equivalent)
- **Scout Block**: Fires before any file read or directory access command

## Don't Use When

- This is a background guard — never invoke manually
- To intentionally access a sensitive file, follow the approval flow below

---

## HARD-GATE: Sensitive File Access

**Blocked file patterns** (privacy-sensitive):
- `.env`, `.env.*`, `.env.local`, `.env.production`, etc.
- `*.pem`, `*.key`, `*.p12`, `*.pfx` (certificates and private keys)
- `*credentials*`, `*secrets*`, `*token*` (credential files)
- `.npmrc`, `.pypirc` (package registry auth files)
- `id_rsa`, `id_ed25519`, `*.ssh/*` (SSH keys)
- `*.credentials.json`, `service-account*.json` (cloud credentials)

**When a sensitive file is accessed without approval:**
1. The read is BLOCKED immediately (exit code 2)
2. A structured privacy prompt is output containing JSON between `@@PRIVACY_PROMPT_START@@` and `@@PRIVACY_PROMPT_END@@`
3. The AI must parse this JSON and present an approval question to the user

**Approval flow:**
```
AI reads ".env" → BLOCKED
  ↓
AI asks user via interactive question:
  "I need to read '.env' which may contain sensitive data. Do you approve?"
  Options: [Yes, approve access] [No, skip this file]
  ↓
User selects "Yes, approve access"
  ↓
AI retries: reads the file using bash (cat ".env") — bash is auto-approved
  ↓
Access granted with notice logged
```

**If user selects "No, skip this file":** Continue without the file.

**Suspicious paths:** If an approved path is outside the project directory, a warning is logged but access is still allowed.

---

## Scout Block: Directory Exclusions

Blocks access to directories listed in `.claude/.ckignore`.

**Default blocked patterns** (gitignore-spec):
- `node_modules/`
- `.git/`
- `dist/`, `build/`, `.next/`
- `*.cache/`
- Any pattern listed in `.ckignore`

**Blocking rules:**
- File paths: blocks any path containing a blocked directory segment
- Bash commands: blocks directory access commands (`cd`, `ls`, `cat`) for blocked dirs

**Allowed despite blocking:**
- Build commands are always allowed: `npm build`, `go build`, `cargo build`, `make`, `mvn`, `gradle`, `docker build`, `kubectl`, `terraform`
- Python venv executables are always allowed
- Negation patterns in `.ckignore` (prefix `!`) re-allow specific paths

**Broad pattern protection:** If a pattern would block too broad a set of paths (e.g., `**` or `/`), a warning is shown with suggestions to use more specific patterns.

---

## Configuration

```json
// $HOME/.claude/.ck.json
{
  "hooks": {
    "privacy-block": true,
    "scout-block": true
  }
}
```

```
# .claude/.ckignore — one pattern per line, # for comments
node_modules/
dist/
.next/
# Allow a specific nested path despite parent being blocked
!node_modules/.bin/
```

---

## Security Properties

- **Fail-open**: Invalid JSON input or unexpected errors allow the operation to continue (never silently breaks workflow)
- **Bash bypass intentional**: Bash commands are warned but not blocked for sensitive files — this enables the "Yes → bash cat" approval flow
- **No secret logging**: Blocked file contents are never logged or included in error messages
- **Approval is session-scoped**: Approval prefix (`APPROVED:`) must be supplied explicitly each time — no persistent approval state