house-rules

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import type { HouseRule } from '../types'
5import { BUILT_IN, broken, describe, parseAdd } from './rules'
6
7const hits = atom({ plugin: 'house-rules', key: 'hits' } as const, {})
8
9const STORE_RULES = 'house-rules.rules'
10const STORE_OFF = 'house-rules.off'
11const STORE_HITS = 'house-rules.hits'
12
13let disabled = new Set<string>()
14let rules: HouseRule[] = BUILT_IN
15
16async function load($: EngineInterface): Promise<HouseRule[]> {
17  const mine = ((await $.store.get(STORE_RULES)) as HouseRule[] | undefined) ?? []
18  const off = new Set([...disabled, ...(((await $.store.get(STORE_OFF)) as string[] | undefined) ?? [])])
19  rules = [...BUILT_IN, ...mine].filter(r => !off.has(r.id))
20  return rules
21}
22
23async function count($: EngineInterface, ids: string[]): Promise<void> {
24  const next = await update($, hits, h => {
25    const c = { ...h }
26    for (const id of ids) c[id] = (c[id] ?? 0) + 1
27    return c
28  })
29  await $.store.set(STORE_HITS, next)
30}
31
32export const register: Register = (on, options) => {
33  disabled = new Set(((options.disabled as readonly string[] | undefined) ?? []).map(String))
34
35  on('session.start', async ($, e, next) => {
36    const started = await next(e)
37    await load($)
38    const stored = (await $.store.get(STORE_HITS)) as Record<string, number> | undefined
39    if (stored) await update($, hits, () => stored)
40    await $.command.register({ name: 'rules', description: 'House rules on tool calls: list, add, turn off or on', argumentHint: '[add <tools> <note|ask|deny> /regex/ <message> | off <id> | on <id>]' })
41    return started
42  })
43
44  // ask: put the call to the person (or the mode's decider) with the rule's reason.
45  on('tool.check', async ($, e, next) => {
46    const asks = broken(rules, String(e.tool), e as unknown as Record<string, unknown>).filter(r => r.action === 'ask')
47    if (!asks.length) return next(e)
48    const verdict = await next(e)
49    if (verdict.decision === 'deny') return verdict
50    await count($, asks.map(r => r.id))
51    return { decision: 'ask', reason: `House rule ${asks[0]?.id}: ${asks[0]?.message}` }
52  }).catch(($, e, next) => next(e))
53
54  // deny refuses before the call runs; note rides along after it.
55  on('tool.call', async ($, e, next) => {
56    const found = broken(rules, String(e.tool), e as unknown as Record<string, unknown>)
57    const deny = found.find(r => r.action === 'deny')
58    if (deny) {
59      await count($, [deny.id])
60      $.ui.toast(`House rule ${deny.id}: refused`)
61      return { deny: `house-rules (${deny.id}): ${deny.message}` }
62    }
63    const notes = found.filter(r => r.action === 'note')
64    if (!notes.length) return next(e)
65    const r = await next(e)
66    if (r.deny !== undefined) return r
67    await count($, notes.map(n => n.id))
68    return { ...r, context: [...(r.context ?? []), ...notes.map(n => `house-rules (${n.id}): ${n.message}`)] }
69  }).catch(($, e, next) => next(e))
70
71  on('command.run', { command: 'rules' }, async ($, e) => {
72    const [verb = '', ...rest] = e.args.trim().split(/\s+/)
73    if (verb === 'add') {
74      const mine = ((await $.store.get(STORE_RULES)) as HouseRule[] | undefined) ?? []
75      const rule = parseAdd(rest.join(' '), `mine-${mine.length + 1}`)
76      if (typeof rule === 'string') return { text: rule }
77      await $.store.set(STORE_RULES, [...mine, rule])
78      await load($)
79      return { text: `Added ${rule.id}: ${rule.action} on ${rule.tools.join(',')} matching /${rule.match[0]}/.` }
80    }
81    if (verb === 'off' || verb === 'on') {
82      const id = rest[0] ?? ''
83      const off = new Set(((await $.store.get(STORE_OFF)) as string[] | undefined) ?? [])
84      if (verb === 'off') off.add(id)
85      else off.delete(id)
86      await $.store.set(STORE_OFF, [...off])
87      await load($)
88      return { text: `${id} is ${verb}.` }
89    }
90    const h = await read($, hits)
91    const all = await load($)
92    return { text: ['House rules:', ...all.map(r => describe(r, h[r.id] ?? 0))].join('\n') }
93  })
94}
95

1// Pure logic for house-rules: the built-in rules and matching a call against them.
2
3import type { HouseRule, RuleAction } from '../types'
4
5export const BUILT_IN: HouseRule[] = [
6  {
7    id: 'appdata-path',
8    tools: ['Write', 'Edit', 'MultiEdit', 'Bash'],
9    // A container mapping or template that names the FUSE path for appdata.
10    match: ['/mnt/user/appdata/[A-Za-z0-9]', '(docker[^"]*\\s(run|create)\\b|\\.xml"|compose|"Type":"Path"|<Config[^>]*Type=\\\\?"Path|\\s-v\\s)'],
11    action: 'note',
12    message:
13      "This server's appdata share lives on the nvme8tb pool and is exclusive: new container paths go to /mnt/nvme8tb/appdata/<app> (no FUSE), as with Prismarr. " +
14      'The Appdata Backup plugin only covers sources under /mnt/user/appdata, so check that whichever path you pick is backed up (zerobyte snapshots the ZFS dataset either way).',
15    isBuiltIn: true,
16  },
17  {
18    id: 'claude-local',
19    tools: ['Bash'],
20    match: ['\\bgit\\s+(add|commit)\\b[^;&|]*CLAUDE\\.local\\.md'],
21    action: 'deny',
22    message: 'CLAUDE.local.md holds environment notes and stays uncommitted in every repo. Leave it out of git add and commits.',
23    isBuiltIn: true,
24  },
25  {
26    id: 'upstream-force-push',
27    tools: ['Bash'],
28    match: ['\\bgit\\s+push\\b[^;&|]*(--force\\b|--force-with-lease|\\s-f\\b|\\s\\+)', '\\bgit\\s+push\\b[^;&|]*\\bupstream\\b'],
29    action: 'deny',
30    message: "Never force-push to an upstream remote (someone else's repo). Push to your fork (origin) and update the PR from there.",
31    isBuiltIn: true,
32  },
33  {
34    id: 'ha-restart',
35    tools: ['mcp__*__ha_restart', 'mcp__*__ha_call_service', 'mcp__*__ha_reload_core'],
36    match: ['(ha_restart|"domain":"homeassistant".*"service":"(restart|stop)"|"service":"homeassistant\\.(restart|stop)"|ha_reload_core)'],
37    action: 'ask',
38    message: 'Restarting Home Assistant interrupts the house (lights, automations, dashboards). David decides when.',
39    isBuiltIn: true,
40  },
41]
42
43export const glob = (pattern: string, s: string): boolean =>
44  new RegExp('^' + pattern.replace(/[.+^${}()|[\]\\]/g, '\\$&').replace(/\*/g, '.*').replace(/\?/g, '.') + '$').test(s)
45
46/** The rules a call breaks, strictest first. `input` is the call's arguments. */
47export function broken(rules: HouseRule[], tool: string, input: Record<string, unknown>): HouseRule[] {
48  const text = JSON.stringify(input) + (tool.includes('__') ? ` ${tool}` : '')
49  const rank: Record<RuleAction, number> = { deny: 0, ask: 1, note: 2 }
50  return rules
51    .filter(r => r.tools.some(t => glob(t, tool)))
52    .filter(r => r.match.every(m => safeTest(m, text)))
53    .filter(r => !r.unless || !safeTest(r.unless, text))
54    .sort((a, b) => rank[a.action] - rank[b.action])
55}
56
57function safeTest(source: string, text: string): boolean {
58  try {
59    return new RegExp(source, 'i').test(text)
60  } catch {
61    return false
62  }
63}
64
65/** `/rules add <tools> <note|ask|deny> /regex/ message` into a rule, or why not. */
66export function parseAdd(args: string, id: string): HouseRule | string {
67  const m = args.match(/^\s*(\S+)\s+(note|ask|deny)\s+\/(.+?)\/\s+(.+)$/)
68  if (!m || !m[1] || !m[2] || !m[3] || !m[4]) return 'Usage: /rules add <tool-glob[,glob]> <note|ask|deny> /regex/ <message>'
69  try {
70    new RegExp(m[3], 'i')
71  } catch (err) {
72    return `That regex doesn't compile: ${err instanceof Error ? err.message : String(err)}`
73  }
74  return { id, tools: m[1].split(','), match: [m[3]], action: m[2] as RuleAction, message: m[4].trim() }
75}
76
77export const describe = (r: HouseRule, hits: number): string =>
78  `${r.id.padEnd(20)} ${r.action.padEnd(5)} ${String(hits).padStart(3)} hits  ${r.tools.join(',')}  ${r.isBuiltIn ? '(built in)' : ''}\n    ${r.message.slice(0, 140)}`
79

1export type RuleAction = 'note' | 'ask' | 'deny'
2
3export type HouseRule = {
4  id: string
5  /** Tool-name globs the rule looks at (Bash, Write, mcp__*__ha_restart). */
6  tools: string[]
7  /** Regexes (source, flags i) on the call's input as JSON; every one must match. */
8  match: string[]
9  /** A regex that, matching, lets the call through. */
10  unless?: string
11  action: RuleAction
12  message: string
13  isBuiltIn?: boolean
14}
15
16declare module 'claude-code' {
17  interface PluginState {
18    'house-rules': {
19      hits: Record<string, number>
20    }
21  }
22}
23