scoped-approve

1import { atom, read, update } from 'claude-code'
2import type { Register } from 'claude-code'
3
4import { allowedBy, parseList } from './allow'
5
6// An APPROVER, not a guard. Rules it never breaks:
7// - it only turns the engine's "ask" into "allow": a deny stays a deny, an allow stays an allow;
8// - only the main conversation (no agentId): subagents keep the normal prompts;
9// - on failure it returns the engine's own verdict (never allow, never deny-everything).
10const approvals = atom({ plugin: 'scoped-approve', key: 'approvals' } as const, [])
11
12export const register: Register = (on, options) => {
13  const list = parseList(String(options.allowList ?? ''))
14  const isEnabled = options.enabled !== false
15
16  on('tool.check', { tool: 'Bash' }, async ($, e, next) => {
17    const decided = await next(e)
18    if (!isEnabled || decided.decision !== 'ask' || e.agentId !== undefined) return decided
19
20    const command = String((e.input as { command?: unknown }).command ?? '')
21    const entry = allowedBy(command, list)
22    if (entry === undefined) return decided
23
24    // Every approval is visible: a dim transcript line, and the session list behind /approvals.
25    $.ui.log(`auto-approved by allow-list entry "${entry}": ${command.slice(0, 120)}`)
26    const at = await $.clock.now()
27    await update($, approvals, l => [...l, { command: command.slice(0, 200), at }].slice(-50))
28    return { decision: 'allow', reason: `scoped-approve: allow-list entry "${entry}"` }
29  }).catch(($, e, next) => next(e))
30
31  on('session.start', async ($, e, next) => {
32    try {
33      await $.command.register({ name: 'approvals', description: 'Show the allow-list and what it approved this session', immediate: true })
34    } catch {
35      // name taken: approvals still work and still log
36    }
37    return next(e)
38  })
39
40  on('command.run', { command: 'approvals' }, async $ => {
41    const done = await read($, approvals)
42    const header = !isEnabled
43      ? 'scoped-approve is off.'
44      : list.length === 0
45        ? 'Allow-list is empty: nothing is auto-approved.'
46        : `Allow-list: ${list.join(' · ')}`
47    const body = done.length === 0 ? 'Nothing approved this session.' : done.map(a => `- ${a.command}`).join('\n')
48    return { text: `${header}\n${body}` }
49  })
50}
51

1// Pure allow-list logic. No $ here, so tests cover it directly.
2
3// Anything that chains, substitutes or redirects is never auto-approved:
4// "git status && rm -rf x" must not ride along with "git status".
5const COMPOUND = /[;&|`<>\n\r]|\$\(/
6
7// An entry is EXACT by default: "git diff" approves "git diff" and nothing else, because arguments can
8// change what a command does ("git diff --output=FILE" overwrites a file). Arguments are accepted only
9// when the entry says so with a trailing " *": "npm test *" approves "npm test" and "npm test -- foo".
10// A "*" anywhere else, or an entry that is only "*", is dropped: it would approve far more than it says.
11const ARGS = ' *'
12
13export function parseList(raw: string): string[] {
14  return raw
15    .split(',')
16    .map(s => s.trim().replace(/\s+/g, ' '))
17    .filter(s => s.length > 0 && !COMPOUND.test(s))
18    .filter(s => {
19      const base = s.endsWith(ARGS) ? s.slice(0, -ARGS.length) : s
20      return base.length > 0 && !base.includes('*')
21    })
22}
23
24// Returns the entry that allows the command, or undefined.
25export function allowedBy(command: string, list: readonly string[]): string | undefined {
26  const cmd = command.trim().replace(/\s+/g, ' ')
27  if (cmd === '' || COMPOUND.test(cmd)) return undefined
28  return list.find(entry => {
29    if (!entry.endsWith(ARGS)) return cmd === entry
30    const base = entry.slice(0, -ARGS.length)
31    return cmd === base || cmd.startsWith(`${base} `)
32  })
33}
34

1export type Approval = { command: string; at: number }
2
3declare module 'claude-code' {
4  interface PluginState {
5    'scoped-approve': { approvals: Approval[] }
6  }
7}
8