synabun 1.3.0 → 2.0.0-beta

package/hooks/claude-code/subagent-start.mjs

@@ -0,0 +1,154 @@
+#!/usr/bin/env node
+
+/**
+ * SynaBun SubagentStart Hook for Claude Code
+ *
+ * Fires when a subagent (Task / AgentTool worker) begins. Mirrors the main
+ * session's UserPromptSubmit auto-recall: it searches SynaBun memory with the
+ * subagent's task text and injects the results into the subagent's context via
+ * `hookSpecificOutput.additionalContext`.
+ *
+ * Subagents never emit UserPromptSubmit, so without this hook they start with
+ * zero memory context. This works for ALL agent types — it only adds context
+ * and requires no tool access from the subagent.
+ *
+ * Finding the task text: SubagentStart carries only the base fields on CLI
+ * 2.1.281 (no prompt). pre-task.mjs stashes every Task/Agent dispatch by
+ * tool_use_id, and Claude Code writes
+ * <dirname(transcript_path)>/<session_id>/subagents/agent-<agent_id>.meta.json
+ * = {agentType, description, toolUseId, …}. In order:
+ *   1. a task field on the input (future hosts),
+ *   2. meta.json → toolUseId → the stash entry,
+ *   3. meta.json → toolUseId → that tool_use in the parent transcript,
+ *   4. exactly one unclaimed stash entry of the same agent type (last 60 s),
+ *   5. otherwise nothing: a guess could brief the worker with another's task.
+ *
+ * The recall is ranked (surface brief-rank) with the relevance floor. Gated by
+ * the hook feature `subagentRecall` (on when absent).
+ */
+
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { readStdin, detectProject, recallMemories, getHookFeatures, hookBudget, clipQuery, transcriptEntries, isTemporaryChat } from './shared.mjs';
+import { claimDispatch } from './task-gate.mjs';
+
+// Cross-platform safety: never break a subagent launch — always emit valid JSON.
+process.on('uncaughtException', () => { try { process.stdout.write('{}'); } catch {} process.exit(0); });
+process.on('unhandledRejection', () => { try { process.stdout.write('{}'); } catch {} process.exit(0); });
+
+const META_POLL_MS = 300;
+
+// The exact field carrying the subagent's task text isn't documented in the CC
+// binary, so probe the known candidates in priority order.
+function extractTaskText(input) {
+  const candidates = [
+    input?.prompt,
+    input?.task_prompt,
+    input?.agent_prompt,
+    input?.description,
+    input?.tool_input?.prompt,
+    input?.tool_input?.description,
+    input?.task?.prompt,
+    input?.task?.description,
+  ];
+  for (const c of candidates) {
+    if (typeof c === 'string' && c.trim()) return c.trim();
+  }
+  return '';
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function readMeta(input) {
+  const { transcript_path: transcriptPath, session_id: sessionId, agent_id: agentId } = input || {};
+  if (typeof transcriptPath !== 'string' || !transcriptPath) return null;
+  if (!/^[a-zA-Z0-9_-]+$/.test(sessionId || '') || !/^[a-zA-Z0-9_-]+$/.test(agentId || '')) return null;
+  const path = join(dirname(transcriptPath), sessionId, 'subagents', `agent-${agentId}.meta.json`);
+  const until = Date.now() + META_POLL_MS;
+  for (;;) {
+    if (existsSync(path)) {
+      try {
+        const meta = JSON.parse(readFileSync(path, 'utf8'));
+        if (meta && typeof meta === 'object') return meta;
+      } catch { /* written but not complete yet: retry */ }
+    }
+    if (Date.now() >= until) return null;
+    await sleep(25);
+  }
+}
+
+function promptFromTranscript(transcriptPath, toolUseId) {
+  for (const entry of transcriptEntries(transcriptPath, 1024 * 1024).reverse()) {
+    if (entry.type !== 'assistant' || !Array.isArray(entry.message?.content)) continue;
+    for (const block of entry.message.content) {
+      if (block && block.type === 'tool_use' && block.id === toolUseId && typeof block.input?.prompt === 'string') {
+        return block.input.prompt;
+      }
+    }
+  }
+  return '';
+}
+
+async function resolveDispatch(input) {
+  const meta = await readMeta(input);
+  const toolUseId = typeof meta?.toolUseId === 'string' ? meta.toolUseId : '';
+  if (toolUseId) {
+    let entry = null;
+    try { entry = claimDispatch(input, { toolUseId }); } catch { /* lock contention: try the transcript */ }
+    if (entry?.prompt?.trim()) return entry.prompt.trim();
+    const fromTranscript = promptFromTranscript(input.transcript_path, toolUseId);
+    if (fromTranscript.trim()) return fromTranscript.trim();
+    return '';
+  }
+  try {
+    const entry = claimDispatch(input, { agentType: input.agent_type || meta?.agentType });
+    if (entry?.prompt?.trim()) return entry.prompt.trim();
+  } catch { /* best effort */ }
+  return '';
+}
+
+async function main() {
+  const budget = hookBudget(3000);
+  let input = {};
+  try {
+    input = JSON.parse(await readStdin());
+  } catch { /* proceed with empty */ }
+
+  // A temporary chat (see isTemporaryChat): no dispatch was stashed for its
+  // workers (pre-task.mjs), so there is no task text to brief them from.
+  if (isTemporaryChat()) { process.stdout.write('{}'); return; }
+
+  // Opt-in payload discovery for verification (SYNABUN_HOOK_DEBUG=1).
+  if (process.env.SYNABUN_HOOK_DEBUG) {
+    try { process.stderr.write(`[SubagentStart] ${JSON.stringify(input)}\n`); } catch { /* ok */ }
+  }
+
+  if (getHookFeatures().subagentRecall === false) { process.stdout.write('{}'); return; }
+
+  const taskText = extractTaskText(input) || await resolveDispatch(input);
+  if (!taskText) { process.stdout.write('{}'); return; }
+
+  const project = detectProject(input.cwd || '');
+  const callMs = Math.min(2000, budget.callTimeout(100));
+  const additionalContext = await recallMemories({
+    query: clipQuery(taskText), project, limit: 3, tokenBudget: 600,
+    timeoutMs: callMs, budgetMs: callMs,
+    // Attribution only: the worker's context holds none of the memories its
+    // parent was shown, so the parent's injection ledger must not filter them.
+    logSessionId: input.session_id,
+    rank: true, surface: 'brief-rank', floor: true,
+  });
+
+  if (additionalContext) {
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'SubagentStart',
+        additionalContext,
+      },
+    }));
+  } else {
+    process.stdout.write('{}');
+  }
+}
+
+main().catch(() => { try { process.stdout.write('{}'); } catch {} process.exit(0); });

package/hooks/claude-code/subagent-stop.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+
+/**
+ * SynaBun SubagentStop Hook for Claude Code
+ *
+ * Fires when a subagent (Task / AgentTool worker) finishes. Mirrors the main
+ * session's Stop auto-remember obligation, but as a SOFT nudge: it injects
+ * `additionalContext` asking the subagent to persist its findings via the
+ * `remember` tool. Per the CC 2.1.177 spec, SubagentStop additionalContext is
+ * "non-error feedback delivered to the subagent; the subagent continues so it
+ * can act on it" — so the worker gets one more turn to call remember.
+ *
+ * Gated behind the `subagentRemember` hook feature (default off) so it's a
+ * deliberate opt-in via the SynaBun settings UI. One nudge per subagent
+ * (tracked by a marker file) to avoid SubagentStop → remember → SubagentStop
+ * loops. Harmless for agents without memory tools — the nudge says to ignore
+ * it when no remember tool is available or nothing substantive was produced.
+ */
+
+import { existsSync, mkdirSync, writeFileSync, readdirSync, statSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+import { readStdin, getHookFeatures, DATA_DIR, isTemporaryChat } from './shared.mjs';
+
+process.on('uncaughtException', () => { try { process.stdout.write('{}'); } catch {} process.exit(0); });
+process.on('unhandledRejection', () => { try { process.stdout.write('{}'); } catch {} process.exit(0); });
+
+const MARKER_DIR = join(DATA_DIR, 'pending-subagent-remember');
+const MARKER_TTL_MS = 24 * 60 * 60 * 1000; // stale-marker cleanup horizon
+
+function sanitizeKey(s) {
+  return String(s || '').replace(/[^a-zA-Z0-9._-]/g, '_').slice(0, 120);
+}
+
+// Opportunistically delete markers older than the TTL so the dir can't grow
+// unbounded (one marker is written per nudged subagent and never re-cleared).
+function cleanupStaleMarkers() {
+  try {
+    const now = Date.now();
+    for (const name of readdirSync(MARKER_DIR)) {
+      const p = join(MARKER_DIR, name);
+      try { if (now - statSync(p).mtimeMs > MARKER_TTL_MS) unlinkSync(p); } catch { /* ok */ }
+    }
+  } catch { /* ok */ }
+}
+
+const NUDGE = [
+  '=== SynaBun: Persist your findings ===',
+  'Before you finish, if you produced findings worth keeping (a fix, a non-obvious',
+  'discovery, an architecture decision, a reusable pattern), call the `remember`',
+  'tool ONCE to store them: include what + why + how, set the project, 3-5 tags,',
+  'and an importance (5=routine, 6-7=significant, 8+=critical).',
+  'Skip this if you have no memory tool available, or did only trivial/read-only',
+  'work with nothing substantive to save.',
+  '=== End ===',
+].join('\n');
+
+async function main() {
+  // Opt-in only.
+  const features = getHookFeatures();
+  if (features.subagentRemember !== true) { process.stdout.write('{}'); return; }
+
+  let input = {};
+  try { input = JSON.parse(await readStdin()); } catch { /* empty */ }
+
+  // A temporary chat (see isTemporaryChat): a worker is not asked to store what it found.
+  if (isTemporaryChat()) { process.stdout.write('{}'); return; }
+
+  if (process.env.SYNABUN_HOOK_DEBUG) {
+    try { process.stderr.write(`[SubagentStop] ${JSON.stringify(input)}\n`); } catch { /* ok */ }
+  }
+
+  // One-shot per subagent: key by agent_id (fallback to session+agent_type).
+  // The marker persists so a worker that stops repeatedly (e.g. stops again
+  // right after acting on the nudge) is never re-nudged. Stale markers are
+  // swept by TTL so the dir can't grow unbounded.
+  const key = sanitizeKey(input.agent_id || `${input.session_id || 's'}-${input.agent_type || 'a'}`);
+  let markerPath = '';
+  try {
+    if (!existsSync(MARKER_DIR)) mkdirSync(MARKER_DIR, { recursive: true });
+    cleanupStaleMarkers();
+    markerPath = join(MARKER_DIR, key);
+  } catch { /* fs unavailable — proceed without loop protection */ }
+
+  if (markerPath && existsSync(markerPath)) {
+    // Already nudged this subagent — stay quiet so it can finish.
+    process.stdout.write('{}');
+    return;
+  }
+
+  if (markerPath) {
+    try { writeFileSync(markerPath, String(Date.now())); } catch { /* ok */ }
+  }
+
+  process.stdout.write(JSON.stringify({
+    hookSpecificOutput: {
+      hookEventName: 'SubagentStop',
+      additionalContext: NUDGE,
+    },
+  }));
+}
+
+main().catch(() => { try { process.stdout.write('{}'); } catch {} process.exit(0); });

package/hooks/claude-code/task-gate.mjs

@@ -0,0 +1,150 @@
+/** Shared, short transactions for the orchestrator's per-prompt recall gate. */
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getDataHome } from '../../lib/paths.js';
+import { updateJsonState, withStateLock, writeJsonAtomic } from './state.mjs';
+
+export const TASK_TOOLS = new Set(['Task', 'Agent']);
+export const RECALL_TOOL = /(?:^|__)Syna[Bb]un_+recall$/;
+const LOCK_OPTIONS = { timeoutMs: 100 };
+
+// --- Subagent dispatch stash ---
+// SubagentStart carries no task text (CLI 2.1.281), so pre-task.mjs records
+// every Task/Agent dispatch here, keyed by tool_use_id, and subagent-start.mjs
+// finds its own through subagents/agent-<id>.meta.json → toolUseId. An
+// ephemeral cache: corrupt content is replaced, entries expire after 10 min.
+const DISPATCH_TTL_MS = 10 * 60 * 1000;
+const DISPATCH_MAX = 50;
+
+function dispatchPath(sessionId) {
+  if (!/^[a-zA-Z0-9_-]+$/.test(typeof sessionId === 'string' ? sessionId : '')) return null;
+  return join(getDataHome(), 'data', 'subagent-dispatch', `${sessionId}.json`);
+}
+
+function readStash(file) {
+  try {
+    const value = JSON.parse(readFileSync(file, 'utf8'));
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+  } catch { return {}; }
+}
+
+const agentType = (value) => (typeof value === 'string' && value.trim() ? value.trim() : 'general-purpose');
+
+/** Record one PreToolUse Task/Agent dispatch. Idempotent per tool_use_id. */
+export function stashDispatch(input) {
+  if (!TASK_TOOLS.has(input?.tool_name) || typeof input.tool_use_id !== 'string' || !input.tool_use_id) return;
+  const file = dispatchPath(input.session_id);
+  if (!file) return;
+  const toolInput = input.tool_input && typeof input.tool_input === 'object' ? input.tool_input : {};
+  const prompt = typeof toolInput.prompt === 'string' ? toolInput.prompt.slice(0, 16000) : '';
+  const description = typeof toolInput.description === 'string' ? toolInput.description.slice(0, 500) : '';
+  if (!prompt.trim() && !description.trim()) return;
+  withStateLock(() => {
+    const now = Date.now();
+    const stash = readStash(file);
+    if (stash[input.tool_use_id]) return;
+    const kept = Object.entries(stash)
+      .filter(([, entry]) => entry && typeof entry === 'object' && now - (Number(entry.at) || 0) < DISPATCH_TTL_MS);
+    kept.push([input.tool_use_id, { prompt, description, subagent_type: agentType(toolInput.subagent_type), at: now }]);
+    kept.sort((a, b) => a[1].at - b[1].at);
+    writeJsonAtomic(file, Object.fromEntries(kept.slice(-DISPATCH_MAX)));
+  }, LOCK_OPTIONS);
+}
+
+/**
+ * Claim the dispatch a subagent was started from. With `toolUseId` (from the
+ * subagent's meta.json) the lookup is exact. Without it, only an unambiguous
+ * guess is made: exactly one unclaimed entry of the same agent type stashed in
+ * the last `windowMs`. Returns {tool_use_id, prompt, description, subagent_type, at} or null.
+ */
+export function claimDispatch(input, { toolUseId, agentType: type, windowMs = 60 * 1000 } = {}) {
+  const file = dispatchPath(input?.session_id);
+  if (!file) return null;
+  let claimed = null;
+  withStateLock(() => {
+    const stash = readStash(file);
+    const now = Date.now();
+    let id = null;
+    if (typeof toolUseId === 'string' && toolUseId) {
+      if (stash[toolUseId] && typeof stash[toolUseId] === 'object') id = toolUseId;
+    } else if (type !== undefined) {
+      const wanted = agentType(type);
+      const matches = Object.entries(stash).filter(([, entry]) => entry && typeof entry === 'object' && !entry.claimed
+        && agentType(entry.subagent_type) === wanted && now - (Number(entry.at) || 0) <= windowMs);
+      if (matches.length === 1) id = matches[0][0];
+    }
+    if (!id) return;
+    const entry = stash[id];
+    claimed = { tool_use_id: id, prompt: String(entry.prompt || ''), description: String(entry.description || ''),
+      subagent_type: agentType(entry.subagent_type), at: Number(entry.at) || 0 };
+    if (!entry.claimed) {
+      stash[id] = { ...entry, claimed: true, claimedBy: typeof input.agent_id === 'string' ? input.agent_id : null, claimedAt: now };
+      writeJsonAtomic(file, stash);
+    }
+  }, LOCK_OPTIONS);
+  return claimed;
+}
+
+function statePath(input) {
+  if (input?.agent_id || !/^[a-zA-Z0-9_-]+$/.test(input?.session_id || '')) return null;
+  return join(getDataHome(), 'data', 'task-gate', `${input.session_id}.json`);
+}
+
+export function startTaskTurn(input) {
+  const file = statePath(input);
+  if (!file || typeof input.prompt !== 'string') return;
+  return updateJsonState(file, state => {
+    // Canonical handlers are deduplicated by Claude; tolerate a duplicate
+    // delivery too, without erasing the receipts from an already-started turn.
+    if (input.prompt_id && state?.promptId === input.prompt_id) return;
+    return {
+      turn: (Number.isSafeInteger(state?.turn) ? state.turn : 0) + 1,
+      promptId: input.prompt_id || null,
+      prompt: input.prompt.trim().slice(0, 16000),
+      completedRecalls: [],
+      blockedToolUseIds: [],
+    };
+  }, undefined, LOCK_OPTIONS);
+}
+
+export function updateTaskTurn(input, update, expectedTurn) {
+  const file = statePath(input);
+  // Old hosts without prompt_id cannot safely attribute a late completion.
+  // Fail open rather than releasing another user prompt's gate.
+  if (!file || typeof input.prompt_id !== 'string' || !input.prompt_id) return;
+  return updateJsonState(file, state => {
+    if (!Number.isSafeInteger(state?.turn) || state.turn < 1
+      || state.promptId !== input.prompt_id
+      || (expectedTurn !== undefined && state.turn !== expectedTurn)) return;
+    return update(state);
+  }, undefined, LOCK_OPTIONS);
+}
+
+export function recordTaskRecall(input) {
+  if (!RECALL_TOOL.test(input.tool_name || '') || !input.tool_use_id) return;
+  return updateTaskTurn(input, state => {
+    if (state.recalledTurn === state.turn || state.releasedTurn === state.turn) return;
+    const ids = state.completedRecalls || [];
+    if (ids.includes(input.tool_use_id)) return;
+    state.completedRecalls = [...ids, input.tool_use_id].slice(-256);
+    return state;
+  });
+}
+
+export function completeTaskBatch(input) {
+  if (!Array.isArray(input.tool_calls)) return;
+  const ids = new Set(input.tool_calls.map(call => call?.tool_use_id).filter(Boolean));
+  if (!ids.size) return;
+  return updateTaskTurn(input, state => {
+    const recalled = (state.completedRecalls || []).some(id => ids.has(id));
+    const blocked = state.blockedTurn === state.turn
+      && (state.blockedToolUseIds || []).some(id => ids.has(id));
+    if (!recalled && !blocked) return;
+    if (recalled) state.recalledTurn = state.turn;
+    if (blocked) state.releasedTurn = state.turn;
+    state.completedRecalls = (state.completedRecalls || []).filter(id => !ids.has(id));
+    delete state.claim;
+    delete state.brief;
+    return state;
+  });
+}

package/lib/claude-hooks.js

@@ -0,0 +1,84 @@
+import { resolve } from 'node:path';
+import { PACKAGE_ROOT } from './paths.js';
+
+// Handler identity must be byte-for-byte identical across settings scopes.
+// Claude Code deduplicates matching settings handlers before executing them.
+export const HOOK_SCRIPTS = Object.freeze([
+  { event: 'SessionStart', script: 'session-start.mjs', timeout: 5 },
+  { event: 'UserPromptSubmit', script: 'prompt-submit.mjs', timeout: 3 },
+  { event: 'PreCompact', script: 'pre-compact.mjs', timeout: 10 },
+  { event: 'Stop', script: 'stop.mjs', timeout: 3 },
+  { event: 'PreToolUse', script: 'pre-websearch.mjs', timeout: 3, matcher: '^WebSearch$|^WebFetch$' },
+  { event: 'PreToolUse', script: 'pre-task.mjs', timeout: 5, matcher: '^Task$|^Agent$' },
+  { event: 'PostToolBatch', script: 'pre-task.mjs', timeout: 3 },
+  { event: 'PostToolUse', script: 'post-remember.mjs', timeout: 3, matcher: '^Edit$|^Write$|^NotebookEdit$|Syna[Bb]un_+(remember|reflect|recall)$' },
+  { event: 'PostToolUse', script: 'post-plan.mjs', timeout: 15, matcher: '^(Enter|Exit)PlanMode$' },
+  { event: 'SubagentStart', script: 'subagent-start.mjs', timeout: 3 },
+  { event: 'SubagentStop', script: 'subagent-stop.mjs', timeout: 3 },
+].map(Object.freeze));
+
+// The batch-completion handler is an installation dependency of the guards.
+// Treat either event as the same group, including direct API callers.
+export function hookDefinitionsForEvent(event) {
+  if (!event) return HOOK_SCRIPTS;
+  const events = ['PreToolUse', 'PostToolBatch'].includes(event)
+    ? ['PreToolUse', 'PostToolBatch'] : [event];
+  return HOOK_SCRIPTS.filter(def => events.includes(def.event));
+}
+
+// No shell-specific environment expansion, install paths, or downloads. Walk
+// up from the project/cwd for checkout-only installs, then use the installed
+// root. Single quotes inside JS work inside the command's double quotes on
+// both cmd.exe and POSIX shells. Keep this versioned literal stable.
+const BOOTSTRAP = "const f=require('node:fs'),p=require('node:path'),u=require('node:url'),s=process.argv[1];let r;const ok=d=>{try{return JSON.parse(f.readFileSync(p.join(d,'package.json'),'utf8')).name==='synabun'&&f.existsSync(p.join(d,'hooks','claude-code',s))}catch{return false}};for(let d=p.resolve(process.env.CLAUDE_PROJECT_DIR||process.cwd());;d=p.dirname(d)){if(ok(d)){r=d;break}if(d===p.dirname(d))break}if(!r&&process.env.SYNABUN_HOOK_ROOT&&ok(process.env.SYNABUN_HOOK_ROOT))r=process.env.SYNABUN_HOOK_ROOT;if(!r)throw Error('SynaBun hook root unavailable; repair the hook installation');import(u.pathToFileURL(p.join(r,'hooks','claude-code',s)).href)";
+
+export function hookCommandString(scriptName) {
+  if (!HOOK_SCRIPTS.some(h => h.script === scriptName)) throw new Error('Unknown SynaBun hook');
+  return `node -e "${BOOTSTRAP}" ${scriptName}`;
+}
+
+export function isSynaBunHookCommand(command, scriptName) {
+  if (typeof command !== 'string') return false;
+  if (command === hookCommandString(scriptName)) return true;
+  // Recognize only the old direct-node path forms, including cross-OS installs.
+  const match = command.trim().match(/^node\s+(?:"([^"]+)"|'([^']+)'|([^\s]+))\s*$/);
+  if (!match) return false;
+  const script = (match[1] || match[2] || match[3]).replace(/\\/g, '/');
+  return script === `hooks/claude-code/${scriptName}` || script.endsWith(`/hooks/claude-code/${scriptName}`);
+}
+
+export function ensureHookRoot(settings, targetProjectPath, packageRoot = PACKAGE_ROOT) {
+  // The checked-in template must not acquire a machine-specific env path.
+  if (targetProjectPath && resolve(targetProjectPath) === resolve(packageRoot)) return false;
+  if (settings.env?.SYNABUN_HOOK_ROOT === resolve(packageRoot)) return false;
+  settings.env = { ...settings.env, SYNABUN_HOOK_ROOT: resolve(packageRoot) };
+  return true;
+}
+
+export function sweepSettingsHooks(settings, targetProjectPath, stats = {}, packageRoot = PACKAGE_ROOT) {
+  if (!settings?.hooks) return false;
+  let changed = false;
+  let ownsHooks = false;
+  for (const def of HOOK_SCRIPTS) {
+    const entries = settings.hooks[def.event];
+    if (!Array.isArray(entries)) continue;
+    const command = hookCommandString(def.script);
+    const matches = entries.flatMap(e => (e.hooks || []).filter(h => isSynaBunHookCommand(h.command, def.script)).map(h => ({ entry: e, hook: h })));
+    if (!matches.length) continue;
+    ownsHooks = true;
+    const canonical = matches.find(({ hook }) => hook.command === command);
+    const matcherOk = canonical && (canonical.entry.matcher || '') === (def.matcher || '');
+    if (matches.length === 1 && matcherOk && canonical.hook.timeout === def.timeout && canonical.hook.type === 'command') continue;
+    stats.removed = (stats.removed || 0) + matches.length - 1;
+    if (!canonical) stats.repaired = (stats.repaired || 0) + 1;
+    else if (!matcherOk) stats.matchers = (stats.matchers || 0) + 1;
+    const rest = entries.flatMap(entry => {
+      const hooks = (entry.hooks || []).filter(h => !isSynaBunHookCommand(h.command, def.script));
+      return hooks.length ? [{ ...entry, hooks }] : [];
+    });
+    settings.hooks[def.event] = [...rest, { matcher: def.matcher || '', hooks: [{ type: 'command', command, timeout: def.timeout }] }];
+    changed = true;
+  }
+  if (ownsHooks && ensureHookRoot(settings, targetProjectPath, packageRoot)) changed = true;
+  return changed;
+}

package/lib/claude-usage-audit.js

@@ -0,0 +1,141 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { createHash } from 'node:crypto';
+
+const USAGE_FIELDS = ['input_tokens', 'cache_creation_input_tokens', 'cache_read_input_tokens', 'output_tokens'];
+const zeroUsage = () => Object.fromEntries(USAGE_FIELDS.map(k => [k, 0]));
+const hash = s => createHash('sha256').update(s).digest('hex');
+export function contentText(content) {
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) return content.map(contentText).join('\n');
+  return content?.type === 'text' ? content.text || '' : '';
+}
+function metrics(content) {
+  const text = contentText(content);
+  return { text_characters: Array.from(text).length, utf8_bytes: Buffer.byteLength(text),
+    images: Array.isArray(content) ? content.filter(b=>b?.type==='image').length : 0,
+    sha256: hash(text), token_count: null, token_count_source: 'unavailable' };
+}
+function isPrompt(record) {
+  if (record.type !== 'user' || record.isMeta || record.isCompactSummary) return false;
+  const content=record.message?.content;
+  if (Array.isArray(content) && (!content.some(b=>b.type==='text') || content.some(b=>b.type==='tool_result'))) return false;
+  if (typeof content !== 'string' && !Array.isArray(content)) return false;
+  return !/^<(local-command|command-name|bash-input|system-reminder)>/.test(contentText(content));
+}
+export function transcriptFiles(directory) {
+  const files=[];
+  for(const entry of readdirSync(directory,{withFileTypes:true})) {
+    const path=join(directory,entry.name);
+    if(entry.isDirectory()) files.push(...transcriptFiles(path));
+    else if(entry.isFile() && entry.name.endsWith('.jsonl'))files.push(path);
+  }
+  return files.sort();
+}
+
+/** Provenance joins are positional; provider usage is never split by character ratios. */
+export function auditClaudeRecords(sources, { since, until } = {}) {
+  const requests=new Map(), prompts=new Map(), payloads=[], groups=new Map();
+  const seenPayloads=new Set();
+  let first=null,last=null;
+  const inWindow=t => t && (!since || Date.parse(t)>=Date.parse(since)) && (!until || Date.parse(t)<=Date.parse(until));
+  for(const {file,records} of sources) {
+    const sidechain=/[/\\]subagents[/\\]/.test(file);
+    const tools=new Map();let prompt=null;
+    // Link only to the first following recorded API response in this file.
+    // This does not assert that a payload survived compaction or was billed.
+    const nextRequests=new Map();let next=null;
+    for(let i=records.length-1;i>=0;i--) {
+      const r=records[i];
+      nextRequests.set(i,next);
+      if(r.type==='assistant' && r.message?.id && r.message?.usage)
+        next={message_id:r.message.id,request_id:r.requestId || r.request_id || null};
+    }
+    for(const [index,r] of records.entries()) {
+      const session=r.sessionId || r.session_id || basename(file,'.jsonl');
+      const content=r.message?.content;
+      if(isPrompt(r)) {
+        prompt=r.promptId || r.uuid || `${file}:${index}`;
+        if(!prompts.has(prompt)) prompts.set(prompt,{id:prompt,session_id:session,sidechain,timestamp:r.timestamp,submitted_in_window:!!inWindow(r.timestamp),request_ids:[]});
+      }
+      if(r.type==='assistant' && Array.isArray(content)) for(const block of content) {
+        if(block.type==='tool_use') tools.set(block.id,{name:block.name,message_id:r.message.id,request_id:r.requestId || r.request_id || null});
+      }
+      if(!inWindow(r.timestamp))continue;
+      if(!first || r.timestamp<first)first=r.timestamp;
+      if(!last || r.timestamp>last)last=r.timestamp;
+      if(r.type==='assistant' && r.message?.id && r.message.usage) {
+        const id=r.message.id, usage=r.message.usage;
+        let entry=requests.get(id);
+        if(!entry) {
+          entry={message_id:id,request_id:r.requestId || r.request_id || null,session_id:session,prompt_id:prompt,
+            sidechain,timestamp:r.timestamp,model:r.message.model,usage:zeroUsage()};
+          requests.set(id,entry);
+          if(prompt)prompts.get(prompt)?.request_ids.push(id);
+        }
+        for(const k of USAGE_FIELDS)if(Number.isFinite(usage[k]))entry.usage[k]=Math.max(entry.usage[k],usage[k]);
+      }
+      const provenance={session_id:session,prompt_id:prompt,timestamp:r.timestamp,sidechain,
+        file,line:index+1,next_recorded_request:nextRequests.get(index),attribution:'next-recorded-request; retention unverified'};
+      const attachment=r.attachment;
+      if(attachment?.type==='hook_additional_context') {
+        const texts=Array.isArray(attachment.content)?attachment.content:[attachment.content];
+        for(const [part,text] of texts.entries()) {
+          if(typeof text!=='string' || !text.includes('SynaBun'))continue;
+          const identity=`${r.uuid || file+':'+index}:${part}`;
+          if(seenPayloads.has(identity))continue;seenPayloads.add(identity);
+          const event=attachment.hookEvent || attachment.hookName || 'unknown';
+          const occurrence=event==='UserPromptSubmit'?prompt:event==='SessionStart'?r.uuid:attachment.toolUseID;
+          const key=JSON.stringify([session,event,occurrence || r.uuid || index]);
+          const payload={...provenance,kind:'hook',hook_event:event,event_key:key,...metrics(text)};
+          payloads.push(payload);
+          if(!groups.has(key))groups.set(key,[]);groups.get(key).push(payload);
+        }
+      }
+      if(r.type==='user' && Array.isArray(content)) for(const b of content) {
+        if(b.type!=='tool_result')continue;
+        const key=`tool:${b.tool_use_id}`;
+        if(seenPayloads.has(key))continue;seenPayloads.add(key);
+        const producer=tools.get(b.tool_use_id);
+        const tool=producer?.name || 'unknown';
+        const short=tool.split(/Syna[Bb]un_+/)[1];
+        const kind=short?.startsWith('browser_')?'synabun_browser':short==='recall'?'synabun_recall':short?'synabun_other':'other_tool';
+        payloads.push({...provenance,kind,tool,tool_use_id:b.tool_use_id,producer,...metrics(b.content)});
+      }
+    }
+  }
+  const requestList=[...requests.values()];
+  const scopeSummary=sidechain=>{
+    const selected=requestList.filter(r=>r.sidechain===sidechain),usage=zeroUsage();
+    for(const r of selected)for(const k of USAGE_FIELDS)usage[k]+=r.usage[k];
+    const active=[...prompts.values()].filter(p=>p.sidechain===sidechain && p.request_ids.length);
+    const input=usage.input_tokens+usage.cache_creation_input_tokens+usage.cache_read_input_tokens;
+    return {requests:selected.length,prompts_submitted:[...prompts.values()].filter(p=>p.sidechain===sidechain && p.submitted_in_window).length,
+      prompts_with_requests:active.length,usage,input_including_cache:input,
+      input_per_active_prompt:active.length?input/active.length:null};
+  };
+  const components={};
+  for(const p of payloads) {
+    const entry=components[p.kind] ||= {payloads:0,text_characters:0,utf8_bytes:0,images:0,token_count:null};
+    entry.payloads++;for(const k of ['text_characters','utf8_bytes','images'])entry[k]+=p[k];
+  }
+  const hooks={};
+  for(const group of groups.values()) {
+    const entry=hooks[group[0].hook_event] ||= {events:0,blocks:0,extra_blocks:0,exact_repeats:0,extra_characters:0};
+    entry.events++;entry.blocks+=group.length;entry.extra_blocks+=group.length-1;
+    entry.exact_repeats+=group.length-new Set(group.map(p=>p.sha256)).size;
+    entry.extra_characters+=group.slice(1).reduce((n,p)=>n+p.text_characters,0);
+  }
+  return {version:1,window:{since:since || first,until:until || last},summary:{main:scopeSummary(false),subagents:scopeSummary(true),components,hooks},
+    accounting_limits:['Provider usage is deduplicated by API message ID; cache fields remain separate.',
+      'Component token counts are unavailable, never estimated from characters.',
+      'Payload request joins identify the next recorded response, not retention or marginal billing.',
+      'Active-prompt averages include prompts submitted before the reporting window.'],
+    requests:requestList,prompts:[...prompts.values()].filter(p=>p.submitted_in_window || p.request_ids.length),payloads};
+}
+
+export function auditClaudeTranscripts(files, options) {
+  return auditClaudeRecords(files.map(file=>({file,records:readFileSync(file,'utf8').split('\n').flatMap(line=>{
+    try{return line.trim()?[JSON.parse(line)]:[];}catch{return [];}
+  })})),options);
+}