receipt

1import type { Register, EngineInterface, ToolGroupCall } from 'claude-code'
2
3// "Verify before claiming." The transcript footer says what the turn actually did (edits, runs,
4// curls), a claim made without a run keeps "unverified claim pending" on the next spinner until
5// something runs, a destructive Bash never folds into a count line, and an edit-without-run turn
6// leaves "run the tests and show the output" as the prompt's ghost text.
7
8const MOD = 'receipt'
9const ENABLED_KEY = 'receipt:enabled'
10const SUGGESTION = 'run the tests and show the output'
11const PENDING = 'unverified claim pending'
12
13const EDIT_TOOLS = ['Edit', 'Write', 'NotebookEdit', 'MultiEdit']
14const READ_TOOLS = ['Read', 'Grep', 'Glob', 'LS']
15const RUNNERS = ['vitest', 'jest', 'pytest', 'mocha', 'tsc']
16const PACKAGE = /^(npm|pnpm|yarn|bun|make)$/
17const WRAPPERS = ['npx', 'bunx', 'sudo']
18const WRITERS = ['tee', 'cp', 'mv', 'touch']
19const QUOTED = '\u0001'
20const REDIRECT = /(?<![<>&\w])\d?&?>{1,2}\s*(?!\/dev\/null)[^\s&|;<>]/
21const DROP_TABLE = /\bdrop\s+table\b/i
22const CLAIM = /\b(deployed|fixed|works now|tests pass|live|verified)\b/i
23
24type Tally = { edits: number; runs: number; curls: number; reads: number; destructive: number }
25
26const fresh = (): Tally => ({ edits: 0, runs: 0, curls: 0, reads: 0, destructive: 0 })
27const ran = (t: Tally) => t.runs + t.curls > 0
28const nag = (t: Tally | undefined) => t !== undefined && t.edits > 0 && !ran(t)
29
30let tally = fresh()
31let last: Tally | undefined
32let pending: Tally | undefined
33const rows = new Map<string, Tally>()
34let claimPending = false
35let enabled = true
36
37const commandOf = (input: unknown) => {
38  const c = typeof input === 'object' && input !== null ? Reflect.get(input, 'command') : undefined
39  return typeof c === 'string' ? c : ''
40}
41
42type Kind = { run: boolean; curl: boolean; edit: boolean; destructive: boolean }
43
44// Heredoc bodies and quoted strings are blanked, then each segment is judged by its first word,
45// so `echo "npm test"` and `grep curl README.md` are neither a run nor a curl.
46const classify = (command: string): Kind => {
47  const kind: Kind = { run: false, curl: false, edit: false, destructive: DROP_TABLE.test(command) }
48  let text = command.replace(/<<-?\s*(['"]?)(\w+)\1[^\n]*\n([\s\S]*?)\n\s*\2(?=\n|$)/g, m => m.slice(0, m.indexOf('\n')))
49  text = text.replace(/'[^']*'|"(?:[^"\\]|\\.)*"/g, QUOTED)
50  for (const segment of text.split(/\n|&&|\|\||[;|]/)) {
51    if (REDIRECT.test(segment)) kind.edit = true
52    const tokens = segment.replace(/\d?&?>{1,2}\s*[^\s&|;<>]+/g, ' ').trim().split(/\s+/).filter(t => !/^\w+=/.test(t))
53    while (tokens.length > 0 && WRAPPERS.includes(tokens[0] ?? '')) tokens.shift()
54    const [cmd = '', ...args] = tokens.map(t => t.replace(/^.*\//, ''))
55    const sub = args.filter(a => !a.startsWith('-'))[0] ?? ''
56    if (RUNNERS.includes(cmd) || ((cmd === 'go' || cmd === 'cargo') && sub === 'test') || (PACKAGE.test(cmd) && /^(test|build)/.test(args[0] === 'run' ? args[1] ?? '' : args[0] ?? '')) || (cmd === 'claude' && args[0] === 'plugin' && args[1] === 'test')) kind.run = true
57    if (cmd === 'curl' || cmd === 'wget') kind.curl = true
58    if (WRITERS.includes(cmd) || (cmd === 'sed' && args.some(a => a === '-i' || a.startsWith('-i') || a.startsWith('--in-place')))) kind.edit = true
59    if ((cmd === 'rm' && args.some(a => /^-\w*r/i.test(a))) || (cmd === 'git' && sub === 'push' && args.some(a => a === '-f' || a === '--force' || a === '--force-with-lease')) || (cmd === 'git' && sub === 'reset' && args.includes('--hard')) || (cmd === 'kubectl' && sub === 'delete')) kind.destructive = true
60  }
61  return kind
62}
63
64const isDestructive = (call: ToolGroupCall) => call.tool === 'Bash' && classify(commandOf(call.input)).destructive
65
66const receipt = (t: Tally) => `${t.edits} edits · ${t.runs} runs${nag(t) ? ' ⚠ no run' : ''}${t.curls > 0 ? ` · ${t.curls} curl` : ''}`
67
68const summary = (t: Tally) => `${t.edits} edits · ${t.runs} runs · ${t.curls} curl · ${t.reads} reads · ${t.destructive} destructive`
69
70let disabled = false
71const readDisabled = async ($: EngineInterface): Promise<boolean> => {
72  const raw = (await $.env.get('CLAUDE_MODS_DISABLE').catch(() => undefined)) ?? ''
73  disabled = raw
74    .split(',')
75    .map(v => v.trim())
76    .some(v => v === 'all' || v === MOD)
77  return disabled
78}
79
80export const register: Register = on => {
81  on('session.start', async ($, e, next) => {
82    const r = await next(e)
83    if (await readDisabled($)) return r
84    enabled = (await $.store.get(ENABLED_KEY).catch(() => undefined)) !== false
85    await $.command
86      .register({
87        name: 'receipt',
88        description: 'Show what each turn did on its footer and flag unverified claims (receipt)',
89        argumentHint: '[on | off | status]',
90        immediate: true,
91      })
92      .catch(err => $.ui.log(`receipt: /receipt not registered: ${err}`))
93    return r
94  })
95
96  on('command.run', { command: 'receipt' }, async ($, e) => {
97    const arg = e.args.trim().toLowerCase()
98    if (arg === 'on' || arg === 'off') {
99      enabled = arg === 'on'
100      await $.store.set(ENABLED_KEY, enabled).catch(err => $.ui.log(`receipt: store write failed: ${err}`))
101      $.ui.invalidate('ui.render')
102      return { text: `receipt ${arg}` }
103    }
104    if (arg === '' || arg === 'status') {
105      return { text: `receipt is ${enabled ? 'on' : 'off'}; this turn: ${summary(tally)}; last turn: ${last ? summary(last) : 'none'}; ${claimPending ? PENDING : 'no claim pending'}` }
106    }
107    return { text: `receipt: "${arg}" is not on, off, or status` }
108  })
109
110  on('turn.start', ($, e, next) => {
111    if (disabled || !enabled) return next(e)
112    tally = fresh()
113    return next(e)
114  })
115
116  on('tool.call', async ($, e, next) => {
117    if (disabled || !enabled) return next(e)
118    const r = await next(e)
119    if (r.deny !== undefined || r.isError) return r
120    if (EDIT_TOOLS.includes(e.tool)) tally.edits++
121    else if (READ_TOOLS.includes(e.tool)) tally.reads++
122    else if (e.tool === 'Bash') {
123      const k = classify(e.command)
124      if (k.run) tally.runs++
125      if (k.curl) tally.curls++
126      if (k.edit) tally.edits++
127      if (k.destructive) tally.destructive++
128      if (k.run || k.curl) claimPending = false
129    }
130    return r
131  })
132
133  on('turn.complete', async ($, e, next) => {
134    const r = await next(e)
135    if (disabled || !enabled || e.agentId !== undefined) return r
136    last = { ...tally }
137    pending = last
138    if (!ran(last) && CLAIM.test(e.answer)) claimPending = true
139    if (nag(last)) void $.prompt.suggest({ text: SUGGESTION }).catch(err => $.ui.log(`receipt: suggestion not shown: ${err}`))
140    return r
141  })
142
143  on('prompt.suggest', ($, e, next) => {
144    if (disabled || !enabled || e.origin.kind !== 'suggestion' || !nag(last)) return next(e)
145    return next({ ...e, text: SUGGESTION })
146  })
147
148  on('ui.render', { component: 'Spinner' }, ($, e, next) => {
149    if (disabled || !enabled || !claimPending || e.surface !== 'terminal') return next(e)
150    const props = e.props.message === null ? { ...e.props, word: `${PENDING} · ${e.props.word}` } : { ...e.props, message: `${PENDING} · ${e.props.message}` }
151    return next({ ...e, props })
152  })
153
154  on('ui.render', { component: 'TurnDuration' }, ($, e, next) => {
155    if (disabled || !enabled || e.surface !== 'terminal') return next(e)
156    let row = rows.get(e.requestId)
157    if (row === undefined && pending !== undefined) {
158      row = pending
159      pending = undefined
160      rows.set(e.requestId, row)
161    }
162    if (row === undefined) return next(e)
163    return next({ ...e, props: { ...e.props, word: `${receipt(row)} · ${e.props.word}` } })
164  })
165
166  on('ui.render', { component: 'ToolGroup' }, ($, e, next) => {
167    if (disabled || !enabled || e.props.isExpanded || !e.props.calls.some(isDestructive)) return next(e)
168    return next({ ...e, props: { ...e.props, isExpanded: true } })
169  })
170}
171