---
name: whitelist-hook
description: L4 Whitelist Hook for bash security. Block all commands except N safelisted patterns. Prevents the L3 marque break (agent writing and running scripts).
user-invocable: true
---

# L4 Bash Whitelist Hook

Apply the L4 whitelist approach to secure an agent against arbitrary bash execution.

## Instructions

To implement an L4 whitelist hook, you need to know:
1. Which agent CLI you're using (Claude Code, Pi, OpenCode)
2. Which commands your agent actually needs to run
3. Whether you want hard block (abort on violation) or soft block (feedback + continue)

## The L4 Pattern

```
All bash -> Check for compound operators (;, &&, ||, |) -> BLOCK
         -> Check against safelist regex patterns        -> ALLOW if match
         -> Everything else                              -> BLOCK
```

## Safelist Design Rules

1. Pin specific scripts: `^npm test$` not `^npm .*$`
2. Never pattern-match an interpreter: `^python .*$` allows running any script
3. Block compound operators before regex checks
4. Audit log all blocks with command + reason

## Example Safelist

```
^npm test$
^npm run build$
^git status$
^git diff$
^uv run pytest
^ls( -la)?( [\w/\.-]+)*$
^cat [\w/\.-]+$
^pwd$
^which [\w-]+$
```

## Implementation

```bash
# Claude Code
cp whitelist.py .claude/hooks/pre_tool_use.py

# Pi Agent
pi -e extensions/whitelist.ts
```

## Verification

Test with:
1. `rm -rf /` -> BLOCKED
2. `npm test` -> ALLOWED
3. `python cleanup.py` -> BLOCKED (the L3 marque break)
4. `npm test && rm -rf /` -> BLOCKED (compound operator)

$ARGUMENTS
