denial-explainer

1import type { Register } from 'claude-code'
2import { explanation, isClassifier } from './explain'
3
4const count = { plugin: 'denial-explainer', key: 'count' } as const
5
6export const register: Register = on => {
7  on('classic.PermissionDenied', async ($, e, next) => {
8    const result = await next(e)
9    if (!isClassifier(e.reason)) return result
10    const held = await $.state.get(count)
11    const n = (held.value ?? 0) + 1
12    await $.state.set(count, n)
13    $.ui.toast(explanation({ tool: e.tool_name, input: e.tool_input, reason: e.reason }, n))
14    return result
15  })
16}
17

1const DANGEROUS = [
2  /(^|[\s;&|(])rm(\s|$)/,
3  /(^|[\s;&|(])sudo(\s|$)/,
4  /\bgit\s+push\b.*(\s-f\b|--force)/,
5  /\|\s*(sudo\s+)?(ba|z|da)?sh\b/,
6]
7const PLAIN_WORD = /^[\w./@:=+-]+$/
8const MAX_ARG = 60
9
10export type Denial = { tool: string; input: unknown; reason: string }
11
12export function isClassifier(reason: string): boolean {
13  return /classifier/i.test(reason) || /\[[^\]]+\]/.test(reason)
14}
15
16export function ruleName(reason: string): string {
17  return reason.match(/\[([^\]]+)\]/)?.[1] ?? 'auto mode'
18}
19
20function field(input: unknown, key: string): string | undefined {
21  const value = (input as Record<string, unknown> | null)?.[key]
22  return typeof value === 'string' ? value : undefined
23}
24
25export function shortArg({ tool, input }: Denial): string {
26  const raw =
27    tool === 'Bash' ? field(input, 'command') : tool === 'WebFetch' ? field(input, 'url') : field(input, 'file_path')
28  if (!raw) return ''
29  const one = raw.replace(/\s+/g, ' ').trim()
30  return one.length > MAX_ARG ? `${one.slice(0, MAX_ARG - 1)}…` : one
31}
32
33function bashRule(command: string | undefined): string | undefined {
34  if (!command || DANGEROUS.some(d => d.test(command))) return undefined
35  const words = command.trim().split(/\s+/).slice(0, 2)
36  if (!words.every(w => PLAIN_WORD.test(w))) return undefined
37  return `Bash(${words.join(' ')}:*)`
38}
39
40function domain(url: string | undefined): string | undefined {
41  if (!url) return undefined
42  try {
43    return new URL(url).hostname || undefined
44  } catch {
45    return undefined
46  }
47}
48
49export function allowRule({ tool, input }: Denial): string | undefined {
50  if (tool === 'Bash') return bashRule(field(input, 'command'))
51  if (tool.startsWith('mcp__')) return tool
52  if (tool === 'WebFetch') {
53    const host = domain(field(input, 'url'))
54    return host && `WebFetch(domain:${host})`
55  }
56  if (tool === 'Edit' || tool === 'Write') {
57    const path = field(input, 'file_path')
58    return path && !path.includes('"') ? `${tool}(${path})` : undefined
59  }
60  return undefined
61}
62
63export function ordinal(n: number): string {
64  const tens = n % 100
65  if (tens >= 11 && tens <= 13) return `${n}th`
66  return `${n}${({ 1: 'st', 2: 'nd', 3: 'rd' } as Record<number, string>)[n % 10] ?? 'th'}`
67}
68
69export function explanation(denial: Denial, count: number): string {
70  const arg = shortArg(denial)
71  const what = arg ? `${denial.tool} ${arg}` : denial.tool
72  const nth = count >= 2 ? ` (${ordinal(count)} this session)` : ''
73  const rule = allowRule(denial)
74  const allow = rule ? `/permissions add "${rule}"` : 'no allow rule suggested'
75  return `Blocked by ${ruleName(denial.reason)}: ${what}${nth}\nAllow it: ${allow}`
76}
77

1declare module 'claude-code' {
2  interface PluginState {
3    'denial-explainer': { count: number }
4  }
5}
6