Safety Features¶

AgentSentinel includes several safety features to prevent accidental approval of dangerous commands.

Dangerous Command Blocking¶

By default, AgentSentinel blocks auto-approval for commands that could cause significant damage.

What Gets Blocked¶

Category	Commands
File deletion	`rm -rf`, `rm -r /`, `sudo rm`
Disk operations	`mkfs`, `dd if=`
Fork bomb	`:(){ :\\|:& };:`
Device write	`> /dev/sda`
Permission changes	`chmod -R 777 /`, `chown -R ... /`
Remote execution	`curl \\| sh`, `curl \\| bash`, `wget \\| sh`, `wget \\| bash`

When Blocking Occurs¶

When a dangerous command is detected:

The prompt is not approved
A warning is logged
If notifications are enabled, you receive an alert
The approval is recorded as "blocked" in stats

WARN dangerous command detected, skipping auto-approval pane=%3

Disabling Danger Blocking¶

Not Recommended

Disabling danger blocking removes an important safety net. Only disable if you understand the risks.

Via CLI flag:

agentsentinel watch --block-danger=false

Via config:

watch:
  block_danger: false

Dry Run Mode¶

Test AgentSentinel without actually sending approvals:

agentsentinel watch --dry-run -v

In dry-run mode:

Prompts are detected and logged
Dangerous commands are flagged
No keystrokes are sent to tmux

This is perfect for:

Testing custom patterns
Verifying detection works correctly
Auditing what would be approved

Example Output¶

INFO prompt detected pane=%1 type=Allow line="Allow? (Y/n)" blocked=false
INFO dry run: would approve pane=%1 count=1

Duplicate Prevention¶

AgentSentinel tracks recently approved panes to prevent sending multiple approvals to the same prompt.

How It Works¶

After approving a pane, it's marked as "recently approved"
For the next 5 seconds, that pane won't receive another approval
This prevents double-approvals when the prompt hasn't cleared yet

Why This Matters¶

Without duplicate prevention:

AgentSentinel detects a prompt and sends y
The AI CLI takes 500ms to process the approval
AgentSentinel scans again, sees the same prompt, sends another y
The extra y might approve something unintended

Custom Danger Patterns¶

Add your own patterns to block:

danger_patterns:
  - "(?i)drop\\s+database"
  - "(?i)truncate\\s+table"
  - "(?i)delete\\s+from.*where\\s+1=1"
  - "(?i)format\\s+c:"
  - "(?i)shutdown\\s+-h"

See Pattern Reference for syntax details.

Notifications¶

Get alerted when dangerous commands are blocked:

agentsentinel watch --notify

Or in config:

notifications:
  enabled: true
  sound: true

You'll receive a macOS notification when:

A prompt is approved
A dangerous command is blocked

Statistics¶

Track blocked commands with stats:

agentsentinel watch --stats

On shutdown, you'll see blocked count:

AgentSentinel Statistics
========================
Total approvals: 15
Blocked (dangerous): 2

Enable logging to file for audit purposes:

stats:
  enabled: true
  log_file: ~/agentsentinel-approvals.log

Each approval is logged as JSON:

{"timestamp":"2024-01-15T10:30:45Z","pane_id":"%1","type":"Allow","line":"Allow? (Y/n)","blocked":false}
{"timestamp":"2024-01-15T10:31:02Z","pane_id":"%2","type":"Allow","line":"rm -rf / (Y/n)","blocked":true}

Best Practices¶

Always test with --dry-run first - Verify detection works before going live
Keep --block-danger enabled - The default is there for a reason
Review custom patterns carefully - Overly broad patterns might match unintended prompts
Use stats logging for audit - Track what's being approved for later review
Enable notifications - Stay aware of blocked commands
Monitor specific sessions - Use --session to limit scope when testing