ai-permission-hook

ai-permission-hook

LLM-evaluated permission hook for Claude Code. Auto-approves safe operations, blocks destructive commands, and delegates ambiguous decisions to a lightweight LLM.

Replaces the abandoned cf-approve npm package with a self-contained Claude Code plugin — zero npm dependencies.

How It Works

Three-tier decision system for Claude Code's PermissionRequest hook:

Tier	Speed	Method	Examples
1	Instant	Pattern matching	Read/Write/Edit → allow; rm -rf / → deny
2	Instant	Cache lookup	SHA256 of {tool, input, cwd} → cached decision
3	~1s	LLM query	Ambiguous Bash commands → GPT-4o-mini evaluates

Skills

Skill	Purpose
/ai-permission-hook:setup	Interactive setup — configure provider, API key, model, register hook
/ai-permission-hook:customize	Edit machine-specific environment rules
/ai-permission-hook:doctor	Diagnose configuration and connectivity issues
/ai-permission-hook:clear-cache	Clear cached permission decisions

Quick Start

1. Install the plugin via the seb-plugins marketplace
2. Run /ai-permission-hook:setup to configure
3. Restart Claude Code

One setup per machine. The hook is registered in ~/.claude/settings.json and all runtime data lives at ~/.claude/permission-hook/ — both are global. Every Claude Code session on the machine shares the same hook, config, cache, and local rules. No per-session setup needed.

Configuration

All runtime data lives at ~/.claude/permission-hook/:

~/.claude/permission-hook/
├── config.json        # API key, model, provider, cache TTL
├── run.sh             # Wrapper script (registered in settings.json)
├── local.md           # Machine-specific environment rules
├── cache/
│   └── approval_cache.json
└── logs/
    └── decisions.jsonl

System Prompt

The LLM evaluator uses a two-layer prompt:

1. Default (config/default-system-prompt.md) — generic security rubric bundled with the plugin
2. Local (~/.claude/permission-hook/local.md) — machine-specific rules you edit with /ai-permission-hook:customize

Tier 1 Fast Decisions

Always allow: Read, Glob, Grep, Write, Edit, MultiEdit, NotebookEdit, TodoWrite, Task, WebFetch, WebSearch, BashOutput, LS, NotebookRead, all mcp__* tools

Always passthrough (user dialog): AskUserQuestion, ExitPlanMode

Always deny (Bash only): 29 destructive command patterns — rm -rf /, force-push to protected branches, fork bombs, credential theft, disk formatting, system file modification

Migration from cf-approve

The setup skill automatically detects an existing cf-approve installation and offers to migrate config, cache, and logs. After migration, uninstall the old package:

npm uninstall -g @abdo-el-mobayad/claude-code-fast-permission-hook

Requirements

• Node.js 18+ (ships with Claude Code)
• An API key for OpenRouter, OpenAI, or Anthropic (for Tier 3 LLM decisions)