session-band

1import { atom, read, update } from 'claude-code'
2import type { EngineInterface, Register } from 'claude-code'
3
4import { composeStatusText, decisionSummary, isBeltDeny } from '../lib/band'
5
6const beltDenies = atom({ plugin: 'session-band', key: 'beltDenies' } as const, 0)
7
8type Logger = { ui: { log: (text: string, options: { to: 'debug' }) => void } }
9type Failed<E, R> = ((e: E) => R) & { event: string; error: { kind: string; message?: string } }
10
11// The one .catch every hook below carries: say why in the debug log, then
12// let the chain beneath answer as if the hook were absent. The line never
13// blocks a turn or a tool call.
14const skipOnFailure = <E, R>($: Logger, e: E, next: Failed<E, R>): R => {
15  const why = next.error.message === undefined ? next.error.kind : `${next.error.kind}: ${next.error.message}`
16  $.ui.log(`session-band: ${next.event} skipped (${why})`, { to: 'debug' })
17  return next(e)
18}
19
20// The text this module instance last pinned; null before its first pin. A
21// hot reload starts over and pins again, and the engine keeps one status
22// line per plugin either way.
23let pinned: string | undefined | null = null
24
25// Recomposes the line and pins it when it changed; undefined clears it.
26async function refreshStatus($: EngineInterface): Promise<void> {
27  const text = composeStatusText(await read($, beltDenies))
28  if (pinned !== null && text === pinned) return
29  pinned = text
30  $.ui.status(text)
31}
32
33export const register: Register = on => {
34  // The count lives in $.state and outlives a reload; the pin does not, so
35  // a count carried across a hot reload is put back on screen here.
36  on('session.start', async ($, e, next) => {
37    const started = await next(e)
38    $.ui.log('session-band: loaded', { to: 'debug' })
39    await refreshStatus($)
40    return started
41  }).catch(skipOnFailure)
42
43  // belt answers PreToolUse as a settings hook beneath every mod; its deny
44  // comes back from next(e) with a `belt[<guard>]: ` reason, possibly inside
45  // the engine's own wrapping. Counted, never changed: the decision returns
46  // exactly as belt made it. Every decision is described in the debug log so
47  // its real shape can be read off `claude --debug`. The line is refreshed
48  // on every call, not only on a deny, so a /clear that zeroed the count
49  // takes the stale line down with it.
50  on('classic.PreToolUse', async ($, e, next) => {
51    const decision = await next(e)
52    if (decision !== undefined) {
53      $.ui.log(`session-band: PreToolUse ${e.tool} decision ${decisionSummary(decision)}`, { to: 'debug' })
54    }
55    if (isBeltDeny(decision)) await update($, beltDenies, n => n + 1)
56    await refreshStatus($)
57    return decision
58  }).catch(skipOnFailure)
59}
60

1// Pure helpers behind the session-band mod: no `$`, no I/O, so `node --test`
2// covers them without the engine. register.tsx is the only caller.
3
4// Every belt denial reason carries `belt[<guard>]: `; other settings hooks
5// deny with their own words. The engine may wrap the reason before a mod
6// sees it (`PreToolUse:Bash hook error: belt[git-push-main]: ...`), so the
7// marker is searched for anywhere in the text, never anchored.
8const BELT_REASON = /belt\[[^\]]+\]:/
9
10/** How many characters of a decision's JSON the debug line keeps. */
11const DECISION_JSON_CAP = 120
12
13/**
14 * Whether a `classic.PreToolUse` decision is a denial belt wrote. A string
15 * `deny` is read as the typed shape; an allow or an ask is never a denial;
16 * any other object is searched as JSON, so a shape the types do not name
17 * (a nested `permissionDecisionReason`, a `block`) still counts.
18 */
19export function isBeltDeny(decision: unknown): boolean {
20  if (decision === null || typeof decision !== 'object') return false
21  const { deny, allow, ask } = decision as { deny?: unknown; allow?: unknown; ask?: unknown }
22  if (typeof deny === 'string') return BELT_REASON.test(deny)
23  if (allow === true || typeof ask === 'string') return false
24  return BELT_REASON.test(stringify(decision))
25}
26
27function stringify(value: unknown): string {
28  try {
29    return JSON.stringify(value) ?? ''
30  } catch {
31    return ''
32  }
33}
34
35/** One debug line's worth of a decision: its keys and the head of its JSON. */
36export function decisionSummary(decision: unknown): string {
37  if (decision === null || typeof decision !== 'object') return `${typeof decision} ${String(decision)}`
38  const keys = Object.keys(decision).join(',')
39  const json = stringify(decision)
40  const head = json.length > DECISION_JSON_CAP ? `${json.slice(0, DECISION_JSON_CAP)}...` : json
41  return `keys [${keys}] ${head}`
42}
43
44/**
45 * The one line pinned under the prompt, or undefined (clear it) before the
46 * first deny. The engine prefixes a status line with the mod's name, so the
47 * text never repeats it.
48 */
49export function composeStatusText(beltDenies: number): string | undefined {
50  return beltDenies > 0 ? `belt denies ${beltDenies}` : undefined
51}
52

1/** How many belt denials this session has seen; zero keeps the line clear. */
2export type SessionBandDenies = number
3
4declare module 'claude-code' {
5  interface PluginState {
6    'session-band': {
7      beltDenies: SessionBandDenies
8    }
9  }
10}
11