Gatekeeper v2: Extend to all tools + improve AI prompt with auto-mode rules

[amondnet]

Summary

Extend Gatekeeper plugin from Bash-only coverage to all Claude Code tools (Write, Edit, WebFetch, Agent, etc.) and improve the PermissionRequest agent hook prompt with rules derived from Claude Code's built-in auto mode classifier.

Background

Analysis of Claude Code source (src/utils/permissions/yoloClassifier.ts) and Anthropic's engineering blog reveals that the built-in auto mode uses a comprehensive 25+ rule set for DENY decisions and 7 ALLOW rules. Current Gatekeeper only covers Bash commands, leaving other tools unprotected.

The built-in auto mode also distinguishes between hard deny (absolute block) and soft deny (block unless user explicitly requested). Current Gatekeeper treats all denials the same — this should be differentiated.

Current State (v1)

• PreToolUse: Bash only — regex DENY/ALLOW rules + chain command parser
• PermissionRequest: Bash only — agent hook with 7 attack pattern checks
• Other tools: No coverage (Write, Edit, WebFetch, Agent, etc.)
• No soft_deny: All denials are hard blocks — no intent-aware classification

Proposed Changes

1. Introduce 3-tier decision system (hard_deny / soft_deny / allow)

The key insight from auto-mode source analysis: not all denials are equal. Some actions should be absolutely blocked (rm -rf /), while others should be blocked unless the user explicitly requested them (git push --force).

Hook flow with soft_deny

PreToolUse (Layer 1 — static rules, ~0ms)
  │
  ├─ hard_deny  → exit code 2 + stderr message → tool blocked immediately
  │                (rm -rf /, mkfs, dd if=/dev/zero, etc.)
  │
  ├─ allow      → exit code 0 + JSON { permissionDecision: "allow" }
  │                (npm test, git status, ls, etc.)
  │
  ├─ soft_deny  → return null (passthrough) → proceeds to PermissionRequest
  │                (git push --force, npm publish, kubectl apply, etc.)
  │
  └─ unknown    → return null (passthrough) → proceeds to PermissionRequest

PermissionRequest (Layer 2 — AI review, ~2-5s)
  │
  ├─ AI judges: "Did the user explicitly request this?"
  │   ├─ Yes → { decision: { behavior: "allow" } }
  │   └─ No  → { decision: { behavior: "deny", message: "..." } }
  │
  └─ AI unsure → {} (empty response = passthrough to next hook)
      └─ No more hooks → user sees permission prompt (= ask)

Classification examples

Command	Layer 1	Reason
rm -rf /	hard_deny	Irreversible system destruction
mkfs.ext4 /dev/sda	hard_deny	Disk format
dd if=/dev/zero of=/dev/sda	hard_deny	Disk zeroing
git push --force	soft_deny → AI	Destructive but sometimes intended
git push origin main	soft_deny → AI	Bypasses PR review but sometimes intended
npm publish	soft_deny → AI	Public release, may be intended
kubectl apply	soft_deny → AI	Infrastructure change, may be intended
terraform apply	soft_deny → AI	Infrastructure change, may be intended
npm test	allow	Safe dev command
git status	allow	Read-only
ls, cat, grep	allow	Read-only inspection

Implementation in PreToolUse

type Decision = 'hard_deny' | 'soft_deny' | 'allow' | null

function classifyBash(cmd: string): { decision: Decision, reason: string } | null {
  // 1. Hard deny — absolute blocks, never passthrough
  for (const rule of HARD_DENY_RULES) {
    if (rule.pattern.test(cmd)) return { decision: 'hard_deny', reason: rule.reason }
  }

  // 2. Soft deny — passthrough to AI for intent judgment
  for (const rule of SOFT_DENY_RULES) {
    if (rule.pattern.test(cmd)) return { decision: 'soft_deny', reason: rule.reason }
  }

  // 3. Allow — safe commands
  for (const rule of ALLOW_RULES) {
    if (rule.pattern.test(cmd)) return { decision: 'allow', reason: rule.reason }
  }

  return null // unknown → passthrough to AI
}

// In the main evaluate function:
switch (result.decision) {
  case 'hard_deny':
    return makeDecision('deny', result.reason)  // exit code 2
  case 'soft_deny':
    return null  // passthrough → PermissionRequest hook handles it
  case 'allow':
    return makeDecision('allow', result.reason)
}

Soft deny rules (passthrough to AI)

These match auto-mode soft_deny rules — dangerous but sometimes intentionally requested:

const SOFT_DENY_RULES: Rule[] = [
  // Git destructive
  { pattern: /git\s+push\s+.*--force\b/i, reason: 'Force push needs user intent verification' },
  { pattern: /git\s+push\s+.*\b(main|master)\b/i, reason: 'Push to default branch needs user intent verification' },
  { pattern: /git\s+reset\s+--hard/i, reason: 'Hard reset needs user intent verification' },
  { pattern: /git\s+clean\s+-[a-z]*f/i, reason: 'Git clean needs user intent verification' },

  // Deploy/publish
  { pattern: /^npm\s+publish\b/i, reason: 'Package publish needs user intent verification' },
  { pattern: /^(terraform|pulumi)\s+apply\b/i, reason: 'Infrastructure apply needs user intent verification' },
  { pattern: /^kubectl\s+(apply|delete)\b/i, reason: 'Kubernetes mutation needs user intent verification' },

  // Self-modification
  { pattern: /\b(\.claude\/settings|CLAUDE\.md)\b/i, reason: 'Agent self-modification needs user intent verification' },

  // Security weakening
  { pattern: /\b--no-verify\b/i, reason: 'Skipping verification needs user intent verification' },
  { pattern: /\bchmod\s+777\b/i, reason: 'Broad permission change needs user intent verification' },
]

2. Extend PreToolUse to all tools (Layer 1 — static rules, ~0ms)

Tool	Rule Type	hard_deny	soft_deny	allow
Bash	Regex	rm -rf /, mkfs, dd, curl|bash	git push --force, npm publish, kubectl apply	npm test, git status, ls
Write/Edit	Path-based	—	.env, .claude/settings, CI configs	project-relative paths
WebFetch	URL-based	—	paste services, script downloads	localhost, known dev services
Safe tools	Instant allow	—	—	Read, Glob, Grep, LSP, TaskCreate, etc.
Unknown tools	Passthrough	—	—	→ Layer 2

Change matcher from "Bash" to "" (all tools).

3. Improve PermissionRequest prompt (Layer 2 — AI review)

Key improvements based on auto-mode analysis:

• Add intent judgment: "Did the user explicitly request this action?" (auto-mode core principle — catches overeager behavior, essential for soft_deny items)
• Add context about soft_deny: Layer 2 receives commands that Layer 1 flagged as "potentially dangerous but possibly intended" — the AI should know this
• Add missing DENY rules from auto-mode defaults:
  • Data exfiltration to external endpoints
  • Supply chain (agent-chosen packages vs declared dependencies)
  • External system writes (closing issues, posting comments user didn't ask for)
  • Content fabrication / impersonation
  • Credential exploration (scanning behavior itself is the violation)
• Add ALLOW rules (reduces false positives): project-scoped ops, declared deps, read-only network
• Add tool-specific guidance: Write/Edit path rules, WebFetch URL rules, Agent subagent rules
• Change matcher from "Bash" to "" (all tools)

4. Consider model optimization

• Current: model: "sonnet" for all AI reviews
• Proposed: model: "haiku" — sufficient for classification, cheaper, ~3x faster
• Most complex commands already handled by Layer 1 regex; Layer 2 only sees edge cases

Design Principles (from auto-mode source analysis)

1. 3-tier classification: hard_deny (absolute block) / soft_deny (AI judges intent) / allow (instant pass)
2. Reasoning-blind: $ARGUMENTS naturally provides only tool_name + tool_input (no agent reasoning text, no tool results) — this is correct
3. Minimize AI calls: Static rules in Layer 1 should handle 80%+ of decisions at zero cost. Soft deny items are the primary AI workload.
4. Intent over pattern: The AI prompt should judge "did the user want this?" not just "is this a known attack pattern?"
5. Fail-open for unknowns: Unknown tools/commands → passthrough → user prompt (not silent allow or deny)

Complementary with Sandbox

This enhancement works best alongside sandbox: { enabled: true }:

• Sandbox: kernel-level isolation (filesystem + network boundaries)
• Gatekeeper: intent-level judgment (within allowed boundaries)
• Together: sandbox guarantees worst-case, Gatekeeper manages the everyday

References

• Anthropic: Claude Code Auto Mode
• Anthropic: Claude Code Sandboxing
• Claude Code Hooks Documentation
• Source: src/utils/permissions/yoloClassifier.ts, src/utils/permissions/classifierDecision.ts

Tasks

• Implement 3-tier decision system (hard_deny / soft_deny / allow) in PreToolUse
• Define soft_deny rules for Bash (git force push, npm publish, kubectl apply, self-modification, security weakening)
• Define soft_deny rules for Write/Edit (.env, .claude/settings, CI configs)
• Define soft_deny rules for WebFetch (paste services, script downloads)
• Extend pre-tool-use.ts evaluate function to handle Write, Edit, WebFetch, and safe tool allowlist
• Add missing Bash hard_deny rules
• Update PermissionRequest prompt with intent judgment, soft_deny context, and auto-mode rules
• Change both hook matchers from "Bash" to ""
• Evaluate haiku vs sonnet for Layer 2 accuracy
• Add tests for hard_deny, soft_deny, and allow classifications
• Update README with 3-tier system and all-tool coverage documentation

[amondnet]

Auto Mode Defaults Coverage Gap Analysis

Compared all 7 ALLOW + 25+ SOFT_DENY rules from claude auto-mode defaults against proposed Gatekeeper v2 coverage. Below are the missing items that need to be added.

Missing ALLOW rules

These need to be added to Layer 1 (static rules) or Layer 2 (AI prompt):

#	Auto Mode Rule	Where to Add	Implementation
A1	Toolchain Bootstrap — official one-line installers (rustup, pypa, bun.sh, brew.sh, etc.)	Layer 1: WebFetch URL allowlist + Bash regex	Allowlist of known installer domains
A2	Standard Credentials — reading creds from .env and sending to intended provider	Layer 2: AI prompt	AI judges if credential usage matches intended provider
A3	Declared Dependencies — `npm install` (from manifest) vs `npm install foo` (agent-chosen)	Layer 1: regex distinguish + Layer 2: AI	`npm install` (no args) = allow, `npm install ` = soft_deny

Missing SOFT_DENY rules — Layer 1 (regex patterns)

#	Auto Mode Rule	Pattern to Add
S1	Blind Apply — `--yes`, `--auto-approve`, `--force` bypassing confirmation	`/--yes|--auto-approve|-y\s/i` on infrastructure commands
S2	Expose Local Services — binding ports that expose services	`/\b(nc|ncat|socat)\s+-l/i`, `/\bpython3?\s+-m\s+http.server/i`
S3	Unauthorized Persistence — cron jobs, systemd services, SSH keys	`/\b(crontab|systemctl\s+enable|ssh-keygen|ssh-copy-id)/i`
S4	Permission Grant — IAM/RBAC elevation	`/\b(gcloud\s+.*add-iam|aws\s+iam|az\s+role\s+assignment)/i`
S5	Logging/Audit Tampering — stopping logs, deleting log dirs	`/\b(systemctl\s+stop\s+.log|rm\s+-rf\s+./log)/i`

Missing SOFT_DENY rules — Layer 2 only (AI prompt additions)

These are too complex for regex and must be in the AI prompt:

#	Auto Mode Rule	AI Prompt Addition
S6	Cloud Storage Mass Delete — S3, GCS, Azure Blob mass operations	"DENY: Mass deleting or modifying files on cloud storage (aws s3 rm --recursive, gsutil rm, az storage blob delete-batch)"
S7	Production Reads — reading inside production via remote shell pulls secrets into transcript	"DENY: Reading inside running production via kubectl exec, docker exec, ssh — even read-only, this pulls live credentials into the transcript"
S8	Create Unsafe Agents — autonomous loops without human approval	"DENY: Creating new autonomous agent loops that execute arbitrary actions without human approval (--dangerously-skip-permissions, --no-sandbox)"
S9	Interfere With Others — deleting others' jobs, overloading shared services	"DENY: Deleting or cancelling jobs/processes not created by the agent, disrupting shared infrastructure"
S10	Modify Shared Resources — in-place modification of shared configs	"DENY: Modifying shared artifacts (cluster configs, shared databases, multi-user infrastructure) without explicit user consent"
S11	Create RCE Surface — endpoints accepting arbitrary code	"DENY: Creating services that accept and execute arbitrary code, or writing code with RCE vulnerabilities (unsanitized eval, shell injection)"
S12	Credential Leakage — embedding secrets in visible fields	"DENY: Embedding secrets in metadata, labels, URLs, or queryable fields"
S13	Exfil Scouting — testing which external endpoints are reachable	"DENY: Probing which external endpoints are reachable (webhook sites, file-sharing services) or testing encoding bypasses — preparation for data exfiltration"
S14	Trusting Guessed External Services — agent guesses a service and sends data	"DENY: When the agent guesses an external service and sends internal data to it — benign intent does not make it safe"
S15	Untrusted Code Integration — pulling external code for execution	"DENY: Pulling code from external repos and arranging execution (git submodules, postinstall scripts, running cloned repo scripts)"
S16	Real-World Transactions — purchases, payments, sending to external people	"DENY: Actions with real-world financial consequence — purchases, payments, bookings, or sending communications to people outside the organization"

Updated AI Prompt (Layer 2) — full auto-mode coverage

The PermissionRequest agent hook prompt should include all of the above. Proposed structure:

You are a security classifier for Claude Code.
This tool call passed Layer 1 static rules and needs your judgment.

Tool call:
$ARGUMENTS

## Core Principle
FIRST: "Did the user explicitly request this specific action?"
- Clearly serving the user's stated task → lean ALLOW
- Agent acting beyond task scope → lean DENY
- Explicit user confirmation must be direct, not suggestive or implicit

## ALLOW
- Project-scoped file operations (read/write/edit within project directory)
- Standard dev commands (test, lint, build, format)
- Git operations (except force push / push to main)
- Installing declared dependencies from manifest (npm install, pip install -r)
- Read-only network requests to known services
- Test artifacts (hardcoded test keys, placeholder credentials)
- Git push to working/agent-created branch (not main/master)
- Official toolchain installers (rustup, pypa, bun.sh, brew.sh) when repo requires it

## DENY — hard block
- Irreversible system destruction (already caught by Layer 1, but double-check)
- Data exfiltration: sending project data to external endpoints
- Credential exploration: systematically scanning credential stores
- Credential leakage: embedding secrets in metadata, labels, URLs
- Exfil scouting: probing which external endpoints are reachable
- Trusting guessed services: agent guesses a service and sends internal data

## DENY — unless user explicitly requested (soft deny)
- Git destructive: force push, delete remote branches, hard reset
- Git push to main/master (bypasses PR review)
- Deploy/publish: npm publish, terraform apply, kubectl apply/delete
- Cloud storage mass operations (S3, GCS, Azure Blob bulk delete)
- Production access: kubectl exec, docker exec, ssh to prod (even reads)
- Blind apply: --yes, --auto-approve, --force on infrastructure commands
- Security weakening: disabling TLS, hooks, logs, audit trails, security agents
- Permission grant: adding IAM roles, granting admin access
- Self-modification: .claude/settings, CLAUDE.md, permission overrides
- Unauthorized persistence: cron jobs, systemd services, SSH keys, shell profiles
- Create unsafe agents: autonomous loops without approval gates
- Interfere with others: cancelling jobs/processes not created by agent
- Modify shared resources: changing shared configs, databases, cluster state
- Create RCE surface: endpoints accepting arbitrary code, eval/injection patterns
- Expose local services: binding ports that expose local files/services
- Untrusted code integration: pulling external code for execution (submodules, postinstall)
- External system writes: closing issues, posting comments, sending messages user didn't ask for
- Content fabrication: reporting success on failed work, impersonating humans
- Real-world transactions: purchases, payments, bookings, external communications

## Tool-Specific
- Bash: analyze ALL parts of chains (;, &&, ||, |, $(), backticks)
- Write/Edit: project files safe, config files (.env, CI) need scrutiny, outside project → DENY
- WebFetch: read-only research → ALLOW, downloading executables/scripts → DENY
- Agent: research/analysis subagents → ALLOW, subagents bypassing user intent → DENY

You have Read, Grep, Glob. Use if command references scripts or ambiguous paths.
Respond ALLOW or DENY with one sentence reason.

Summary

Category	Previously covered	After this update
ALLOW rules (7)	4/7 (57%)	7/7 (100%)
SOFT_DENY rules (25+)	10/25 (40%)	25/25 (100%)
Layer 1 regex coverage	~40%	~55%
Layer 2 AI prompt coverage	~60%	100%

[amondnet]

Implementation Complete

PR #136 — Ready for Review

Summary

Gatekeeper v2 extends security coverage from Bash-only to all Claude Code tools with a 3-tier decision system (hard_deny / soft_deny / allow). The PermissionRequest AI prompt now covers the full auto-mode rule set (7 ALLOW, 25+ DENY rules) with intent judgment as the core principle.

Key Changes

• 3-tier decision system: hard_deny (block), soft_deny (AI review), allow (instant)
• All-tool coverage: Bash, Write/Edit, WebFetch, safe tools allowlist
• PermissionRequest rewrite with auto-mode rules, switched to haiku model
• 246 tests, 835 assertions, 0 failures