doctor

Permission Hook Diagnostics

Run a comprehensive health check on the ai-permission-hook installation. Report issues and suggest fixes.

Diagnostic Checks

Run all checks and present results as a checklist.

1. Config File

Read ~/.claude/permission-hook/config.json. Check:

• File exists
• Valid JSON
• Has llm.provider field
• Has llm.apiKey field (non-empty)
• Has llm.model field
• Has llm.baseUrl field

2. Hook Registration

Read ~/.claude/settings.json. Check:

• hooks.PermissionRequest array exists
• At least one entry has "command" containing permission-hook/run.sh
• Matcher is "*" (covers all tools)

3. Wrapper Script

Check ~/.claude/permission-hook/run.sh:

• File exists
• Is executable
• Contains a valid path to permission-handler.js
• The referenced permission-handler.js file actually exists at that path

If the path in run.sh points to a non-existent file (stale after plugin update), report this clearly and suggest re-running /ai-permission-hook:setup to update the path.

4. API Connectivity

Make a minimal test call to the configured LLM endpoint. Read the config to get the base URL, API key, and model, then send a lightweight chat completion request:

node -e "
const fs = require('fs');
const https = require('https');
const http = require('http');
const cfg = JSON.parse(fs.readFileSync(require('os').homedir() + '/.claude/permission-hook/config.json', 'utf8'));
const url = new URL((cfg.llm.baseUrl || 'https://openrouter.ai/api/v1').replace(/\/+$/, '') + '/chat/completions');
const mod = url.protocol === 'https:' ? https : http;
const body = JSON.stringify({ model: cfg.llm.model, messages: [{ role: 'user', content: 'Reply OK' }], max_tokens: 5 });
const req = mod.request({ hostname: url.hostname, port: url.port || 443, path: url.pathname, method: 'POST', headers: { 'Authorization': 'Bearer ' + cfg.llm.apiKey, 'Content-Type': 'application/json' }, timeout: 10000 }, (res) => {
  let data = ''; res.on('data', c => data += c);
  res.on('end', () => console.log(res.statusCode >= 200 && res.statusCode < 300 ? 'OK: API connectivity verified' : 'ERROR: HTTP ' + res.statusCode + ' - ' + data.slice(0, 100)));
});
req.on('error', e => console.log('ERROR: ' + e.message));
req.on('timeout', () => { req.destroy(); console.log('ERROR: Request timed out'); });
req.write(body); req.end();
"

Report: success, HTTP error, network error, or auth error.

5. Cache Stats

Read ~/.claude/permission-hook/cache/approval_cache.json:

• Number of cached entries
• Age of oldest entry (hours)
• Number of expired entries (older than configured TTL)

6. Log Stats

Check ~/.claude/permission-hook/logs/decisions.jsonl:

• File exists
• Number of entries (line count)
• File size
• Last entry timestamp

7. Local Override

Check ~/.claude/permission-hook/local.md:

• File exists (optional — report if missing but don't flag as error)
• Non-empty content

8. Legacy cf-approve

Check if ~/.claude-code-fast-permission-hook/ still exists:

• If present, suggest running /ai-permission-hook:setup to migrate and then uninstalling: npm uninstall -g @abdo-el-mobayad/claude-code-fast-permission-hook

Output Format

Present results as a checklist:

Configuration:
  Provider: openrouter
  Model: gpt-4o-mini
  API Key: (set)
  Base URL: https://openrouter.ai/api/v1

Hook Registration: (registered in settings.json, matcher: *)

Wrapper Script: (valid, points to existing handler)

API Connectivity: (success)

Cache: 142 entries, oldest 312 hours ago

Logs: 1,847 entries, 245 KB, last entry 2 hours ago

Local Override: (configured, 15 lines)

Legacy cf-approve: not found

Flag any issues with clear fix suggestions.