YWR Labs Harness

1// Hooks module (Claude Mods, Claude Code 2.1.287+; ADR 0117, ADR 0118) — the OBSERVE-ONLY per-request
2// delegation ledger. `hooks.json` names this file under `modules`; the settings hooks beside it are
3// unaffected.
4//
5// What it records, per finished model loop (the main loop's turn, or one run of a subagent's loop):
6// every request the loop made (`turn.step`: the model the engine resolved, the effort it sends, the
7// usage the API reported), the loop's end (`turn.complete`: reason, duration, summed usage) and, for
8// a spawned agent, the spawn itself (`agent.spawn`: type, the per-call model as given, the parent
9// model, the resolved model). An agent-team teammate raises `agent.spawn` too from Claude Code 2.1.289
10// (`e.isTeammate`); its loop keeps the `agent-tool` kind and its spawn row says `teammate: true`, which
11// is what the reader splits on (schema 2 unchanged — the field is additive). A Workflow `agent()` worker
12// raises `agent.spawn` from Claude Code 2.1.292 with `e.workflow` ({runId, agentIndex}); its spawn row
13// carries `workflow: {run_id, agent_index}` and its loop is kind `workflow` (ADR 0126), and a row with
14// no `model_param` proves the call gave no model, so the worker inherited the session's. On 2.1.287 to
15// 2.1.291 such a worker raises no `agent.spawn` (fact 89): its loop is written with `spawn: null` and
16// `loop: 'unspawned'`, whose steps still name the model and effort it ran on. On 2.1.292+ `unspawned`
17// means an evicted spawn row.
18//
19// Observe-only, by contract: every hook passes the event on unchanged (`next(e)`, `yield* next(e)`),
20// never rewrites `model`/`effort`, never denies, never draws, and swallows its own failures — the
21// recording code runs after `next` resolved and inside try/catch, because a hook that fails
22// mid-stream is "left where it stood". It never carries a gate: hosts < 2.1.287, `disableAllHooks`,
23// `--safe-mode` and a managed `allowManagedModsOnly` all drop it (ADR 0117).
24//
25// What it never writes: a prompt, a task description, an answer or any other message text (the
26// secret-adjacent rule `subagent-telemetry` keeps). Where it writes (ADR 0118): a RING of twenty
27// session files, `<project root>/.claude/telemetry/delegations/slot-00.json`..`slot-19.json` —
28// gitignored by the scaffold and the canon — and only where the root holds `.harness.json` (a repo
29// that adopted the harness), so a session in a home directory or a stranger's checkout leaves nothing
30// behind. `$.fs` has no delete, so the bound is by construction: a session claims a missing slot or
31// the oldest by `mtimeMs`, and its file keeps its last 500 loops within 360 KiB. `$.fs.write` is not
32// atomic and replaces the whole file, so a session's writes are serialized, and a slot another
33// session took (its `mtimeMs`/`size` moved since this session's last write) is given up for a new one.
34//
35// The pure half (`createLedger`, `createSessionLog`, `pickSlot`, `stepRow`, `spawnRow`, `fingerprint`)
36// is exported so `delegation-ledger.selftest.ps1` drives it under plain node with a fake engine; the
37// engine imports only `register`.
38
39export const SCHEMA = 2
40export const LEDGER_DIR = '.claude/telemetry/delegations'
41export const RING = 20
42// One session file: its last MAX_LOOPS loops within MAX_FILE_BYTES (UTF-8, counted as an upper
43// bound). The ring's worst case is RING x MAX_FILE_BYTES, ~7 MiB per adopted repo.
44export const MAX_LOOPS = 500
45export const MAX_FILE_BYTES = 360 * 1024
46// Room left in MAX_FILE_BYTES for the file's own fields around `loops` (a session id is ~40 B).
47const HEADER_RESERVE = 1024
48// A loop keeps its first MAX_STEPS step rows; the rest are counted. Bounds one row (~67 B a step)
49// and the memory of an open loop.
50export const MAX_STEPS = 200
51// Open loops are held in module memory until their loop ends. A loop that never ends (killed agent,
52// crash) would otherwise leak; past this many, the oldest is dropped unwritten.
53export const MAX_OPEN = 256
54// Spawn rows outlive their loop (a resumed agent runs again under the same id), so they are capped
55// separately and higher (a row is ~300 B). An evicted row would make that agent's later run read as
56// `unspawned` — the workflow signal ADR 0117 Decision 6 counts on hosts before 2.1.292, and a plain
57// eviction after — so each record carries `spawn_rows_evicted`, the session's running count, and a
58// reader discounts `unspawned` when it is > 0.
59export const MAX_SPAWNS = 4096
60// Session loop lists held at once (a `/clear` starts a new session in the same module).
61export const MAX_SESSIONS = 4
62
63const MAIN = 'main'
64
65export function slotName(i) {
66  return `slot-${String(i).padStart(2, '0')}.json`
67}
68
69// The slot a new session claims from a `$.fs.list` of the ledger directory: the lowest-numbered slot
70// with no entry, else the regular slot file with the oldest `mtimeMs` (ties: the lowest number), else
71// null. A slot name that is a directory, a link or anything but a file is never claimed.
72export function pickSlot(entries, ring = RING) {
73  const byName = new Map()
74  for (const en of Array.isArray(entries) ? entries : []) if (en && typeof en.name === 'string') byName.set(en.name, en)
75  let oldest = null
76  for (let i = 0; i < ring; i++) {
77    const en = byName.get(slotName(i))
78    if (!en) return i
79    if (en.kind !== 'file' || en.isLink || typeof en.mtimeMs !== 'number') continue
80    if (oldest === null || en.mtimeMs < oldest.mtimeMs) oldest = { i, mtimeMs: en.mtimeMs }
81  }
82  return oldest ? oldest.i : null
83}
84
85// An upper bound on the UTF-8 length of a string: a code unit above U+007F counts 3 bytes (a
86// surrogate pair counts 6 for its 4).
87export function utf8Bound(s) {
88  let n = s.length
89  for (let i = 0; i < s.length; i++) if (s.charCodeAt(i) > 0x7f) n += 2
90  return n
91}
92
93function usageRow(u) {
94  if (!u || typeof u !== 'object') return null
95  return {
96    model: u.model ?? null,
97    input_tokens: u.input_tokens ?? 0,
98    output_tokens: u.output_tokens ?? 0,
99    cache_read_input_tokens: u.cache_read_input_tokens ?? 0,
100    cache_creation_input_tokens: u.cache_creation_input_tokens ?? 0,
101  }
102}
103
104export function spawnRow(e, r) {
105  const wf = e.workflow && typeof e.workflow === 'object' ? e.workflow : null
106  return {
107    tool_use_id: e.tool_use_id ?? null,
108    subagent_type: e.subagentType ?? null,
109    provider: e.provider ? `${e.provider.plugin}/${e.provider.tier}` : null,
110    model_param: e.model ?? null,
111    parent_model: e.parentModel ?? null,
112    model: r && typeof r === 'object' && !('deny' in r && r.deny) ? (r.model ?? null) : null,
113    denied: !!(r && typeof r === 'object' && r.deny),
114    fork: !!e.fork,
115    background: !!e.background,
116    teammate: !!e.isTeammate,
117    workflow: wf ? { run_id: wf.runId ?? null, agent_index: wf.agentIndex ?? null } : null,
118    parent_agent_id: e.parentAgentId ?? null,
119  }
120}
121
122// A step row is a TUPLE in STEP_FIELDS order (~67 B, against ~236 B as an object): the ledger is
123// read by analysis code, never by eye, and the file names the fields once, as `step_fields`. The
124// token counts are null when the request reported no usage; `usage_model` (the model the API
125// reported) is null when it equals `model` or no usage came back.
126export const STEP_FIELDS = ['index', 'model', 'effort', 'message_count', 'stop_reason', 'input_tokens',
127  'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens', 'usage_model']
128
129export function stepRow(e, r) {
130  const res = r && typeof r === 'object' ? r : null
131  const u = usageRow(res ? res.usage : null)
132  const model = e.model ?? null
133  return [
134    e.index ?? null,
135    model,
136    e.effort ?? null,
137    e.messageCount ?? null,
138    res ? (res.stopReason ?? null) : null,
139    u ? u.input_tokens : null,
140    u ? u.output_tokens : null,
141    u ? u.cache_read_input_tokens : null,
142    u ? u.cache_creation_input_tokens : null,
143    u && u.model !== model ? u.model : null,
144  ]
145}
146
147const present = x => x !== null && x !== undefined
148
149// The ledger's bookkeeping, engine-free. `spawn` / `step` / `complete` take the event and the result
150// `next` resolved to; `complete` answers the loop's row (empty steps when nothing was open).
151export function createLedger({ maxOpen = MAX_OPEN, maxSpawns = MAX_SPAWNS, maxSteps = MAX_STEPS } = {}) {
152  const spawns = new Map()   // agentId -> spawn row (kept across that agent's runs)
153  const open = new Map()     // `${agentId|main}\u0000${turnId}` -> { steps, dropped, models, efforts }
154  let evicted = 0
155  const cap = (map, max, onDrop) => { while (map.size > max) { map.delete(map.keys().next().value); onDrop?.() } }
156  const key = (agentId, turnId) => `${agentId ?? MAIN}\u0000${turnId}`
157  return {
158    spawn(e, r) {
159      const agentId = r && typeof r === 'object' ? r.agentId : undefined
160      if (!agentId) return
161      spawns.set(agentId, spawnRow(e, r))
162      cap(spawns, maxSpawns, () => { evicted++ })
163    },
164    step(e, r) {
165      const k = key(e.agentId, e.turnId)
166      if (!open.has(k)) { open.set(k, { steps: [], dropped: 0, models: new Set(), efforts: new Set() }); cap(open, maxOpen) }
167      const loop = open.get(k)
168      if (!loop) return
169      const row = stepRow(e, r)
170      if (present(row[1])) loop.models.add(row[1])
171      if (present(row[2])) loop.efforts.add(row[2])
172      if (loop.steps.length < maxSteps) loop.steps.push(row)
173      else loop.dropped++
174    },
175    complete(e, { iso }) {
176      const k = key(e.agentId, e.turnId)
177      const loop = open.get(k) ?? { steps: [], dropped: 0, models: new Set(), efforts: new Set() }
178      open.delete(k)
179      const spawn = e.agentId ? (spawns.get(e.agentId) ?? null) : null
180      return {
181        ts: iso,
182        loop: !e.agentId ? MAIN : !spawn ? 'unspawned' : spawn.workflow ? 'workflow' : 'agent-tool',
183        agent_id: e.agentId ?? null,
184        turn_id: e.turnId ?? null,
185        spawn,
186        spawn_rows_evicted: evicted,
187        steps: loop.steps,
188        steps_dropped: loop.dropped,
189        models: [...loop.models],
190        efforts: [...loop.efforts],
191        complete: {
192          reason: e.reason ?? null,
193          aborted: !!e.isAborted,
194          duration_ms: e.durationMs ?? null,
195          usage: usageRow(e.usage),
196        },
197      }
198    },
199    sizes: () => ({ spawns: spawns.size, open: open.size, evicted }),
200  }
201}
202
203// One session's loop rows, kept serialized and capped; `render` is the whole file's text.
204export function createSessionLog({ maxLoops = MAX_LOOPS, maxBytes = MAX_FILE_BYTES } = {}) {
205  const loops = []   // { text, bytes }
206  let bytes = 0
207  let dropped = 0
208  return {
209    add(row) {
210      const text = JSON.stringify(row)
211      const b = utf8Bound(text) + 1   // + its comma
212      loops.push({ text, bytes: b })
213      bytes += b
214      while (loops.length > maxLoops || (loops.length > 0 && bytes + HEADER_RESERVE > maxBytes)) {
215        bytes -= loops.shift().bytes
216        dropped++
217      }
218    },
219    // `header` is the file's own fields; `loops` goes last, spliced in as the rows' kept text.
220    render(header) {
221      const h = JSON.stringify({ ...header, loops_dropped: dropped, loops: [] })
222      return `${h.slice(0, -3)}[${loops.map(l => l.text).join(',')}]}\n`
223    },
224    sizes: () => ({ loops: loops.length, bytes, dropped }),
225  }
226}
227
228// --- the engine half ---------------------------------------------------------------------------
229// Declared at the top of the file: the engine follows `$` only into such functions.
230
231// The project root to write under, or null where the root holds no `.harness.json`. `adopted`
232// caches the answer per root (a `/cd` or worktree move changes the root mid-session).
233async function target($, adopted) {
234  const root = await $.session.root()
235  if (!adopted.has(root)) adopted.set(root, await $.fs.exists(`${root}/.harness.json`))
236  return adopted.get(root) ? root : null
237}
238
239async function statOf($, path) {
240  try {
241    const st = await $.fs.stat(path)
242    return { mtimeMs: st.mtimeMs, size: st.size }
243  } catch { return null }
244}
245
246// The start every file this session renders begins with (`render` puts the header keys first).
247const headerOf = id => `{"schema":${SCHEMA},"session_id":${JSON.stringify(id)},`
248
249// A 32-bit FNV-1a over the UTF-16 code units: the mark of the text this session last wrote whole.
250export function fingerprint(text) {
251  let h = 0x811c9dc5
252  for (let i = 0; i < text.length; i++) h = Math.imul(h ^ text.charCodeAt(i), 0x01000193)
253  return h >>> 0
254}
255
256// One rewrite of a session's file. Runs on the session's chain, never two at once for one session.
257async function flush($, s, root, iso) {
258  const dir = `${root}/${LEDGER_DIR}`
259  if (s.root !== root) { s.root = root; s.slot = null; s.seen = null; s.mark = null }
260  if (s.slot !== null && s.seen) {
261    const now = await statOf($, `${dir}/${slotName(s.slot)}`)
262    // moved since this session's last write: another session claimed it. A stat that fails (a missing
263    // slot among the causes) proves nothing either way, so the read-back below decides.
264    if (!now) s.seen = null
265    else if (now.mtimeMs !== s.seen.mtimeMs || now.size !== s.seen.size) s.slot = null
266  }
267  if (s.slot !== null && !s.seen) {
268    // the last write or a stat failed, so there is no stat to compare: the file itself says whose
269    // it is. A missing or empty file stays ours; so does the very text this session last wrote whole
270    // (its fingerprint, which covers a stat that keeps failing), and a file starting with our own
271    // header (a partial write of ours keeps it). A file that exists but cannot be read proves
272    // nothing, and neither does a null session id's header (every id-less session writes the same
273    // one), so both are given up.
274    const path = `${dir}/${slotName(s.slot)}`
275    let text = ''
276    try { text = await $.fs.read(path) } catch {
277      let there = true
278      try { there = await $.fs.exists(path) } catch { /* unknown: not provably ours */ }
279      if (there) text = null
280    }
281    const ours = text === '' || (text !== null && ((s.mark !== null && fingerprint(text) === s.mark) ||
282      (s.id !== null && text.startsWith(headerOf(s.id)))))
283    if (!ours) s.slot = null
284  }
285  if (s.slot === null) {
286    let entries = []
287    try { entries = await $.fs.list(dir) } catch { /* no directory yet: every slot is missing */ }
288    s.slot = pickSlot(entries)
289    if (s.slot === null) return
290  }
291  const path = `${dir}/${slotName(s.slot)}`
292  const text = s.log.render({ schema: SCHEMA, session_id: s.id, slot: s.slot, updated: iso, step_fields: STEP_FIELDS })
293  s.seen = null
294  s.mark = null
295  await $.fs.write(path, text)
296  s.mark = fingerprint(text)
297  s.seen = await statOf($, path)
298}
299
300export function register(on) {
301  const ledger = createLedger()
302  const adopted = new Map()    // project root -> whether it holds .harness.json
303  const sessions = new Map()   // session id -> { id, log, root, slot, seen, mark, chain }
304  const sessionOf = id => {
305    let s = sessions.get(id)
306    if (s) { sessions.delete(id); sessions.set(id, s) }   // most recently used last: eviction takes the idlest
307    else {
308      s = { id, log: createSessionLog(), root: null, slot: null, seen: null, mark: null, chain: Promise.resolve() }
309      sessions.set(id, s)
310      while (sessions.size > MAX_SESSIONS) sessions.delete(sessions.keys().next().value)
311    }
312    return s
313  }
314
315  on('agent.spawn', async ($, e, next) => {
316    const r = await next(e)
317    try { ledger.spawn(e, r) } catch { /* observe-only: never fail the spawn */ }
318    return r
319  })
320
321  on('turn.step', async function* ($, e, next) {
322    const r = yield* next(e)
323    try { ledger.step(e, r) } catch { /* observe-only */ }
324    return r
325  })
326
327  on('turn.complete', async ($, e, next) => {
328    const r = await next(e)
329    try {
330      // The loop leaves memory first: a failing engine call below costs this one record, never a leak.
331      const row = ledger.complete(e, { iso: null })
332      const id = (await $.session.id()) ?? null
333      row.ts = new Date(await $.clock.now()).toISOString()
334      const root = await target($, adopted)
335      if (root) {
336        const s = sessionOf(id)
337        s.log.add(row)
338        const run = s.chain.then(() => flush($, s, root, row.ts))
339        s.chain = run.catch(() => {})
340        await run
341      }
342    } catch { /* observe-only: a ledger write never reaches the turn */ }
343    return r
344  })
345}
346