attesso 0.4.1 → 0.6.0

package/src/policy.mjs

@@ -65,33 +65,33 @@ export function validatePolicy(policy) {
 // names one cause rather than a list.
 export function evaluate(policy, proposal, now = new Date()) {
   if (policy.action !== '*' && proposal.action !== policy.action) {
-    return { decision: 'DENY', code: 'ACTION_MISMATCH' };
+    return { decision: 'DENY', code: 'ACTION_MISMATCH', rule: 'policy.action' };
   }
   if (policy.subjects !== undefined) {
     if (typeof proposal.subject !== 'string') {
-      return { decision: 'DENY', code: 'REQUIRED_ATTRIBUTE_MISSING' };
+      return { decision: 'DENY', code: 'REQUIRED_ATTRIBUTE_MISSING', rule: 'policy.subjects' };
     }
     if (!policy.subjects.includes(proposal.subject)) {
-      return { decision: 'DENY', code: 'VALUE_NOT_ALLOWED' };
+      return { decision: 'DENY', code: 'VALUE_NOT_ALLOWED', rule: 'policy.subjects' };
     }
   }
   if (policy.max_amount !== undefined) {
     if (!proposal.amount || !Number.isInteger(proposal.amount.minor)) {
-      return { decision: 'DENY', code: 'REQUIRED_ATTRIBUTE_MISSING' };
+      return { decision: 'DENY', code: 'REQUIRED_ATTRIBUTE_MISSING', rule: 'policy.max_amount' };
     }
     if (proposal.amount.currency !== policy.currency) {
-      return { decision: 'DENY', code: 'VALUE_MISMATCH' };
+      return { decision: 'DENY', code: 'VALUE_MISMATCH', rule: 'policy.currency' };
     }
     if (proposal.amount.minor > policy.max_amount) {
-      return { decision: 'DENY', code: 'ABOVE_MAXIMUM' };
+      return { decision: 'DENY', code: 'ABOVE_MAXIMUM', rule: 'policy.max_amount' };
     }
   }
   const at = now.getTime();
   if (policy.on_or_after && at < Date.parse(policy.on_or_after)) {
-    return { decision: 'DENY', code: 'OUTSIDE_DATE_RANGE' };
+    return { decision: 'DENY', code: 'OUTSIDE_DATE_RANGE', rule: 'policy.on_or_after' };
   }
   if (policy.on_or_before && at > Date.parse(policy.on_or_before)) {
-    return { decision: 'DENY', code: 'OUTSIDE_DATE_RANGE' };
+    return { decision: 'DENY', code: 'OUTSIDE_DATE_RANGE', rule: 'policy.on_or_before' };
   }
   return { decision: ALLOW, code: ALLOW };
 }

package/src/receipt.mjs

@@ -0,0 +1,104 @@
+// A receipt is one entry, its path to the root, and a signed checkpoint. It is
+// self-contained: a verifier needs the public key, nothing else.
+import { sign, verify } from 'node:crypto';
+import { canonical } from './canonical.mjs';
+import { inclusionPath, leafHash, merkleRoot, prefixRoot, verifyInclusion } from './merkle.mjs';
+
+const encode = (buffer) => buffer.toString('base64url');
+const decode = (text) => Buffer.from(text, 'base64url');
+
+// The key file and the signer object carry the same three facts under different
+// names; map once so a command never spells the clump out again.
+export const signerOf = (key) => ({ kid: key.kid, privatePem: key.private, publicPem: key.public });
+
+export function checkpointFor(entries, { kid, privatePem, at = new Date() }) {
+  const body = {
+    v: 1,
+    origin: `attesso.local/${kid}`,
+    size: entries.length,
+    root: encode(merkleRoot(entries.map(leafHash))),
+    at: at.toISOString(),
+  };
+  const sig = sign(null, Buffer.from(canonical(body)), privatePem).toString('base64url');
+  return { ...body, sig };
+}
+
+export function verifyCheckpoint(checkpoint, publicPem) {
+  if (!checkpoint || typeof checkpoint.sig !== 'string') return false;
+  const { sig, ...body } = checkpoint;
+  if (
+    body.v !== 1 ||
+    typeof body.origin !== 'string' ||
+    !Number.isInteger(body.size) ||
+    typeof body.root !== 'string' ||
+    body.root === ''
+  ) {
+    return false;
+  }
+  return verify(null, Buffer.from(canonical(body)), publicPem, Buffer.from(sig, 'base64url'));
+}
+
+export function receiptFor(entries, index, { kid, privatePem, publicPem }) {
+  const entry = entries[index];
+  if (!entry) throw new Error(`no entry at index ${index}`);
+  const leaves = entries.map(leafHash);
+  return {
+    v: 1,
+    entry,
+    leaf_index: index,
+    tree_size: entries.length,
+    path: inclusionPath(leaves, index).map(encode),
+    checkpoint: checkpointFor(entries, { kid, privatePem }),
+    key: publicPem,
+  };
+}
+
+export function verifyReceipt(receipt, publicPem) {
+  if (!receipt || receipt.v !== 1 || !receipt.entry || !Array.isArray(receipt.path)) {
+    return { ok: false, reason: 'receipt is not version 1' };
+  }
+  if (!Number.isInteger(receipt.leaf_index) || !Number.isInteger(receipt.tree_size) || receipt.tree_size < 1) {
+    return { ok: false, reason: 'receipt has no integer index and tree size' };
+  }
+  if (!receipt.path.every((hash) => typeof hash === 'string' && hash !== '')) {
+    return { ok: false, reason: 'receipt path is not a list of hashes' };
+  }
+  if (receipt.entry.seq !== receipt.leaf_index + 1) {
+    return { ok: false, reason: 'leaf index does not match the entry sequence' };
+  }
+  const key = publicPem ?? receipt.key;
+  if (!verifyCheckpoint(receipt.checkpoint, key)) {
+    return { ok: false, reason: 'checkpoint signature does not verify' };
+  }
+  if (receipt.checkpoint.size !== receipt.tree_size) {
+    return { ok: false, reason: 'checkpoint size does not match the receipt' };
+  }
+  const ok = verifyInclusion(
+    leafHash(receipt.entry),
+    receipt.leaf_index,
+    receipt.tree_size,
+    receipt.path.map(decode),
+    decode(receipt.checkpoint.root),
+  );
+  return ok
+    ? { ok: true, reason: `entry #${receipt.entry.seq} is in the tree of ${receipt.tree_size}` }
+    : { ok: false, reason: 'the entry is not in the tree its proof names' };
+}
+
+// The pin is the only thing an attacker with the key cannot re-derive. It is
+// checked against the local log, so the log must be present.
+export function verifyPinned(entries, checkpoint, publicPem) {
+  if (!verifyCheckpoint(checkpoint, publicPem)) {
+    return { ok: false, reason: 'pinned checkpoint signature does not verify' };
+  }
+  if (!Number.isInteger(checkpoint.size) || checkpoint.size < 0) {
+    return { ok: false, reason: 'pinned checkpoint has no size' };
+  }
+  if (entries.length < checkpoint.size) {
+    return { ok: false, reason: `the log holds ${entries.length} entries, fewer than the pinned ${checkpoint.size}` };
+  }
+  if (!prefixRoot(entries, checkpoint.size).equals(decode(checkpoint.root))) {
+    return { ok: false, reason: 'the log was rewritten below the pinned head' };
+  }
+  return { ok: true, reason: `log extends the pinned head at ${checkpoint.size} entries` };
+}

package/src/replay.mjs

@@ -0,0 +1,133 @@
+// Re-judge a recorded ledger under a candidate policy. The ledger is a record of
+// attempts, so every entry stays in the history even when it was refused: that is
+// what makes an observe-mode run replayable.
+import { decide } from './decide.mjs';
+import { argsHashOf, deniedCapabilities } from './rules.mjs';
+
+export const proposalOf = (entry) => ({
+  action: entry.action,
+  subject: entry.subject,
+  amount: entry.amount,
+  task: entry.task,
+  trust: entry.trust,
+  capability: entry.capability,
+  args_hash: argsHashOf(entry),
+  meta: entry.meta,
+});
+
+// A rule can only be defeated by a field this entry would have needed to match
+// it. One web-only same-arguments rule must not make every other tool
+// unenforceable, or a replay cannot judge the rows it is meant to compare.
+const matchesTrigger = (trigger, entry) => {
+  if (trigger.trust && trigger.trust !== entry.trust) return false;
+  if (trigger.subject && trigger.subject !== entry.subject) return false;
+  if (trigger.capability && entry.capability !== undefined && trigger.capability !== entry.capability) return false;
+  return true;
+};
+
+function needsArguments(entry, rules) {
+  return (rules?.rules ?? []).some((rule) => {
+    const trigger = rule.if_path ?? {};
+    if (trigger.same_arguments) {
+      if (!matchesTrigger(trigger, entry)) return false;
+      // Without a capability, the missing-field check below reports the gap.
+      return !(trigger.capability && entry.capability === undefined);
+    }
+    if (rule.max_repeats !== undefined) {
+      if (entry.capability !== undefined) {
+        const denied = deniedCapabilities(rule);
+        if (!denied.includes(entry.capability)) return false;
+      }
+      return true;
+    }
+    return false;
+  });
+}
+
+// A candidate rule may read a field this entry never stored. Say so instead of
+// reporting a clean allow the rule could not actually have reached.
+function missingFields(entry, rules) {
+  const reasons = [];
+  const pathRules = (rules?.rules ?? []).filter(
+    (rule) => rule.if_path?.trust !== undefined || rule.if_path?.capability !== undefined,
+  );
+  if (
+    pathRules.some(
+      (rule) => rule.if_path?.capability && matchesTrigger(rule.if_path, entry) && !entry.capability,
+    )
+  ) {
+    reasons.push('NO_CAPABILITY');
+  }
+  if (needsArguments(entry, rules) && argsHashOf(entry) === undefined) reasons.push('NO_ARGUMENTS');
+  return reasons;
+}
+
+export function replay(entries, { policy, rules }) {
+  const histories = new Map();
+  const summary = {
+    total: entries.length,
+    original_denials: entries.filter((entry) => entry.decision !== 'ALLOW').length,
+    candidate_denials: 0,
+    denial_rate: 0,
+    unchanged: 0,
+    newly_allowed: 0,
+    newly_denied: 0,
+    unenforceable: 0,
+    changed: [],
+    unenforceable_rows: [],
+  };
+  for (const entry of entries) {
+    const key = entry.task ?? null;
+    const history = histories.get(key) ?? [];
+    const from = { decision: entry.decision, code: entry.code };
+    if (entry.control) {
+      summary.unchanged += 1;
+      history.push(entry);
+      histories.set(key, history);
+      continue;
+    }
+    const reasons = missingFields(entry, rules);
+    if (reasons.length > 0) {
+      summary.unenforceable += 1;
+      summary.unenforceable_rows.push({ seq: entry.seq, reasons });
+    } else {
+      const to = decide({ policy, rules, history, proposal: proposalOf(entry), now: new Date(entry.at) });
+      if (to.decision === from.decision && to.code === from.code) {
+        summary.unchanged += 1;
+      } else {
+        if (from.decision === 'ALLOW' && to.decision === 'DENY') summary.newly_denied += 1;
+        if (from.decision !== 'ALLOW' && to.decision === 'ALLOW') summary.newly_allowed += 1;
+        summary.changed.push({
+          seq: entry.seq,
+          action: entry.action,
+          subject: entry.subject,
+          task: entry.task ?? null,
+          from,
+          to: { decision: to.decision, code: to.code, rule: to.rule ?? null },
+        });
+      }
+    }
+    history.push(entry);
+    histories.set(key, history);
+  }
+  summary.candidate_denials = summary.original_denials - summary.newly_allowed + summary.newly_denied;
+  summary.denial_rate = entries.length === 0 ? 0 : summary.candidate_denials / entries.length;
+  return summary;
+}
+
+export function renderReplay(summary) {
+  const percent = `${Math.round(summary.denial_rate * 100)}%`;
+  const lines = [
+    `${summary.total} entries: ${summary.candidate_denials} refusals under the candidate (${percent}), ` +
+      `${summary.unchanged} unchanged, ${summary.newly_denied} newly denied, ` +
+      `${summary.newly_allowed} newly allowed, ${summary.unenforceable} unenforceable`,
+  ];
+  for (const row of summary.changed.slice(0, 10)) {
+    const subject = row.subject ? ` ${row.subject}` : '';
+    lines.push(`  #${row.seq} ${row.from.decision}/${row.from.code} -> ${row.to.decision}/${row.to.code} ${row.action}${subject}`);
+  }
+  for (const row of summary.unenforceable_rows.slice(0, 10)) {
+    lines.push(`  #${row.seq} unenforceable (${row.reasons.join(', ')})`);
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/report.mjs

@@ -2,46 +2,88 @@
 // stop": per task, how many actions ran, how many were refused and why, and the
 // tokens and money the task spent. Costs come from a llm.session entry the
 // recorder writes, never from an estimate the report invents.
-import { readState } from './store.mjs';
+import { paths, readKey, readState } from './store.mjs';
+import { forEachEntry } from './stream.mjs';
 
 const isSpend = (entry) => entry.action === 'llm.session';
-const isAction = (entry) => !isSpend(entry);
 
-function summarise(entries) {
-  const actions = entries.filter(isAction);
-  const blocked = actions.filter((entry) => entry.decision !== 'ALLOW');
-  const reasons = new Map();
-  for (const entry of blocked) {
-    const key = entry.code ?? 'UNKNOWN';
-    reasons.set(key, (reasons.get(key) ?? 0) + 1);
-  }
-  const sum = (field) => entries.reduce((total, entry) => total + (Number(entry.meta?.[field]) || 0), 0);
+const emptyGroup = () => ({
+  actions: 0,
+  blocked: 0,
+  reasons: new Map(),
+  tokens: 0,
+  cached_tokens: 0,
+  cost_usd: 0,
+  api_calls: 0,
+});
+
+const add = (group, entry) => {
+  const meta = entry.meta ?? {};
+  group.tokens += Number(meta.tokens) || 0;
+  group.cached_tokens += Number(meta.cached_tokens) || 0;
+  group.cost_usd += Number(meta.cost_usd) || 0;
+  group.api_calls += Number(meta.api_calls) || 0;
+  if (isSpend(entry)) return;
+  group.actions += 1;
+  if (entry.decision === 'ALLOW') return;
+  group.blocked += 1;
+  const code = entry.code ?? 'UNKNOWN';
+  group.reasons.set(code, (group.reasons.get(code) ?? 0) + 1);
+};
+
+function finish(group) {
   return {
-    actions: actions.length,
-    allowed: actions.length - blocked.length,
-    blocked: blocked.length,
-    blocked_share: actions.length === 0 ? null : blocked.length / actions.length,
-    reasons: [...reasons.entries()].sort((left, right) => right[1] - left[1]).map(([code, count]) => ({ code, count })),
-    tokens: sum('tokens'),
-    cached_tokens: sum('cached_tokens'),
-    cost_usd: Number(sum('cost_usd').toFixed(6)),
-    api_calls: sum('api_calls'),
+    actions: group.actions,
+    allowed: group.actions - group.blocked,
+    blocked: group.blocked,
+    blocked_share: group.actions === 0 ? null : group.blocked / group.actions,
+    reasons: [...group.reasons.entries()]
+      .sort((left, right) => right[1] - left[1])
+      .map(([code, count]) => ({ code, count })),
+    tokens: group.tokens,
+    cached_tokens: group.cached_tokens,
+    cost_usd: Number(group.cost_usd.toFixed(6)),
+    api_calls: group.api_calls,
+  };
+}
+
+function reportOf(groups, count, kid, all) {
+  return {
+    key: kid,
+    entries: count,
+    tasks: [...groups.entries()]
+      .map(([task, group]) => ({ task, ...finish(group) }))
+      .sort((left, right) => right.actions - left.actions),
+    totals: finish(all),
   };
 }
 
 export function buildReport(dir) {
   const { entries, key } = readState(dir);
   const groups = new Map();
+  const all = emptyGroup();
   for (const entry of entries) {
+    add(all, entry);
     const task = entry.task ?? '(unscoped)';
-    if (!groups.has(task)) groups.set(task, []);
-    groups.get(task).push(entry);
+    if (!groups.has(task)) groups.set(task, emptyGroup());
+    add(groups.get(task), entry);
   }
-  const tasks = [...groups.entries()]
-    .map(([task, rows]) => ({ task, ...summarise(rows) }))
-    .sort((left, right) => right.actions - left.actions);
-  const totals = summarise(entries);
-  return { key: key.kid, entries: entries.length, tasks, totals };
+  return reportOf(groups, entries.length, key.kid, all);
+}
+
+export async function buildReportStream(dir) {
+  const key = readKey(dir);
+  const groups = new Map();
+  const all = emptyGroup();
+  let count = 0;
+  await forEachEntry(paths(dir).ledger, (entry) => {
+    count += 1;
+    add(all, entry);
+    const task = entry.task ?? '(unscoped)';
+    if (!groups.has(task)) groups.set(task, emptyGroup());
+    add(groups.get(task), entry);
+  });
+  return reportOf(groups, count, key.kid, all);
 }
 
 const percent = (share) => (share === null ? 'n/a' : `${Math.round(share * 100)}%`);

package/src/rules.mjs

@@ -4,13 +4,57 @@
 import { createHash } from 'node:crypto';
 import { canonical } from './canonical.mjs';
 
-export const CAPABILITIES = ['read', 'send', 'execute', 'spend'];
+export const CAPABILITIES = ['read', 'write', 'send', 'execute', 'spend'];
+export const RULE_PROFILES = ['balanced', 'strict'];
 export const TRUST_LEVELS = ['internal', 'untrusted', 'unknown'];
 
+// One policy, two postures. Balanced catches the outbound boundary and duplicate
+// fetches; strict keeps the old conservative posture for an untrusted
+// environment, where a shell command itself can exfiltrate.
+export function rulesForProfile(profile = 'balanced') {
+  const untrustedRead = { trust: 'untrusted', capability: 'read', within_minutes: 30 };
+  const repeatWeb = {
+    capability: 'read',
+    subject: 'web_extract',
+    same_arguments: true,
+    within_minutes: 30,
+  };
+  if (profile === 'balanced') {
+    return {
+      version: 1,
+      rules: [
+        { id: 'no-send-after-untrusted-read', deny: { capabilities: ['send'] }, if_path: { ...untrustedRead } },
+        { id: 'no-repeat-web-extract', deny: { capabilities: ['read'] }, if_path: { ...repeatWeb } },
+      ],
+    };
+  }
+  if (profile === 'strict') {
+    return {
+      version: 1,
+      rules: [
+        { id: 'no-send-after-untrusted-read', deny: { capabilities: ['send', 'write', 'execute'] }, if_path: { ...untrustedRead } },
+        { id: 'no-repeat-web-extract', deny: { capabilities: ['read'] }, if_path: { ...repeatWeb } },
+      ],
+    };
+  }
+  throw new Error(`unknown rule profile ${profile}; choose ${RULE_PROFILES.join(' or ')}`);
+}
+
+// Entries written before the argument fingerprint moved out of meta keep it
+// there; every reader goes through this helper so both shapes agree.
+export const argsHashOf = (value) => value?.args_hash ?? value?.meta?.args_hash;
+
 export function rulesDigest(rules) {
   return createHash('sha256').update(canonical(rules)).digest('base64url');
 }
 
+// One reading of a rule's deny block, shared by validation and evaluation.
+export function deniedCapabilities(rule) {
+  const deny = rule.deny ?? {};
+  if (deny.all) return CAPABILITIES;
+  return deny.capabilities ?? (deny.capability ? [deny.capability] : []);
+}
+
 export function validateRules(rules) {
   const fail = (message) => {
     throw new Error(`rules are invalid: ${message}`);
@@ -20,8 +64,7 @@ export function validateRules(rules) {
   if (!Array.isArray(rules.rules)) fail('rules must be a list');
   for (const rule of rules.rules) {
     if (typeof rule.id !== 'string' || rule.id === '') fail('every rule needs an id');
-    const deny = rule.deny ?? {};
-    const denies = deny.all ? CAPABILITIES : (deny.capabilities ?? (deny.capability ? [deny.capability] : []));
+    const denies = deniedCapabilities(rule);
     if (denies.length === 0) fail(`rule ${rule.id} denies nothing`);
     for (const capability of denies) {
       if (!CAPABILITIES.includes(capability)) fail(`rule ${rule.id} denies unknown capability ${capability}`);
@@ -52,8 +95,7 @@ export function validateRules(rules) {
 export function evaluatePath(rules, history, proposal, now = new Date()) {
   if (!rules) return null;
   for (const rule of rules.rules ?? []) {
-    const deny = rule.deny ?? {};
-    const denied = deny.all ? CAPABILITIES : (deny.capabilities ?? (deny.capability ? [deny.capability] : []));
+    const denied = deniedCapabilities(rule);
     if (proposal.capability && !denied.includes(proposal.capability)) continue;
 
     // A ceiling on the task itself. This is the rule that stops a runaway loop,
@@ -62,11 +104,16 @@ export function evaluatePath(rules, history, proposal, now = new Date()) {
       return { decision: 'DENY', code: 'STEP_LIMIT', rule: rule.id, tainted_by: history.length };
     }
     if (rule.max_repeats !== undefined) {
-      const repeats = history.filter(
-        (entry) => entry.subject === proposal.subject && entry.meta?.args_hash === proposal.meta?.args_hash,
-      );
-      if (repeats.length >= rule.max_repeats) {
-        return { decision: 'DENY', code: 'REPEAT_LIMIT', rule: rule.id, tainted_by: repeats[0].seq };
+      const proposalHash = argsHashOf(proposal);
+      // Without a fingerprint a repeat cannot be identified; counting every call
+      // with the same subject would refuse the second unrelated command.
+      if (proposalHash !== undefined) {
+        const repeats = history.filter(
+          (entry) => entry.subject === proposal.subject && argsHashOf(entry) === proposalHash,
+        );
+        if (repeats.length >= rule.max_repeats) {
+          return { decision: 'DENY', code: 'REPEAT_LIMIT', rule: rule.id, tainted_by: repeats[0].seq };
+        }
       }
     }
     const trigger = rule.if_path ?? {};
@@ -78,7 +125,7 @@ export function evaluatePath(rules, history, proposal, now = new Date()) {
       if (trigger.trust && entry.trust !== trigger.trust) return false;
       if (trigger.capability && entry.capability !== trigger.capability) return false;
       if (trigger.subject && entry.subject !== trigger.subject) return false;
-      if (trigger.same_arguments && entry.meta?.args_hash !== proposal.meta?.args_hash) return false;
+      if (trigger.same_arguments && argsHashOf(entry) !== argsHashOf(proposal)) return false;
       if (window > 0 && now.getTime() - Date.parse(entry.at) > window) return false;
       return true;
     });

package/src/serve.mjs

@@ -38,8 +38,10 @@ export function serve(dir, { observe = false, input = process.stdin, output = pr
         id: request.id ?? null,
         decision: entry.decision,
         code: entry.code,
-        reason: entry.meta?.rule
-          ? `${entry.meta.rule} (tainted by step #${entry.meta.tainted_by})`
+        reason: entry.rule
+          ? entry.tainted_by === undefined
+            ? entry.rule
+            : `${entry.rule} (tainted by step #${entry.tainted_by})`
           : null,
         enforced: entry.decision === 'ALLOW' || observe ? false : true,
         seq: entry.seq,

package/src/setup.mjs

@@ -4,9 +4,10 @@
 //   setup    detect a harness, wire the hook, leave a short block the agent reads
 //   explain  one ledger entry in full, including what tainted the path
 //   suggest  rules the ledger's own counts justify, ready to accept
-import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { join } from 'node:path';
+import { join, resolve } from 'node:path';
+import { argsHashOf } from './rules.mjs';
 
 const AGENT_BLOCK = `<!-- attesso:start -->
 A veto is active on your tool calls. When a call is refused you get a tool error naming
@@ -20,7 +21,7 @@ function stripAgentBlock(text) {
 }
 
 export function writeAgentContext(dir, { dryRun = false } = {}) {
-  const path = join(process.cwd(), 'AGENTS.md');
+  const path = join(resolve(dir), 'AGENTS.md');
   const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
   const next = `${stripAgentBlock(existing).trimEnd()}\n\n${AGENT_BLOCK}\n`;
   if (dryRun) return { path, changed: next !== existing, preview: AGENT_BLOCK };
@@ -28,52 +29,45 @@ export function writeAgentContext(dir, { dryRun = false } = {}) {
   return { path, changed: next !== existing };
 }
 
-function hermesConfig() {
-  return join(homedir(), '.hermes', 'config.yaml');
-}
-
-const HOOK_BLOCK = (cli, dir) => `hooks:
-  pre_tool_call:
-    - command: ${cli} --dir ${dir} hook --observe
-      timeout: 10
-`;
-
 export function detectHarnesses({ home = homedir(), cwd = process.cwd() } = {}) {
   const found = [];
   const hermes = join(home, '.hermes', 'config.yaml');
   if (existsSync(hermes)) found.push({ key: 'hermes', path: hermes });
-  const claude = join(cwd, '.claude', 'settings.json');
+  const claude = join(home, '.claude', 'settings.json');
   if (existsSync(claude)) found.push({ key: 'claude-code', path: claude });
-  const cursor = join(cwd, '.cursor', 'hooks.json');
+  const projectClaude = join(cwd, '.claude', 'settings.json');
+  if (existsSync(projectClaude) && projectClaude !== claude) found.push({ key: 'claude-code-project', path: projectClaude });
+  const codex = join(home, '.codex', 'hooks.json');
+  if (existsSync(codex)) found.push({ key: 'codex', path: codex });
+  const gemini = join(home, '.gemini', 'settings.json');
+  if (existsSync(gemini)) found.push({ key: 'gemini', path: gemini });
+  const cline = join(home, '.cline');
+  if (existsSync(cline)) found.push({ key: 'cline', path: join(home, 'Documents', 'Cline', 'Hooks') });
+  const cursor = join(home, '.cursor', 'hooks.json');
   if (existsSync(cursor)) found.push({ key: 'cursor', path: cursor });
+  const projectCursor = join(cwd, '.cursor', 'hooks.json');
+  if (existsSync(projectCursor) && projectCursor !== cursor) found.push({ key: 'cursor-project', path: projectCursor });
   return found;
 }
 
-// Hermes is the one harness we verify end to end today, so it is the only one we
-// modify. For the others we print the snippet: writing a config format we have not
-// tested against the real product would be a guess, and a guess in a config file is
-// worse than a line of instructions.
-export function wireHermes(cli, dir, { dryRun = false, path = hermesConfig() } = {}) {
-  if (!existsSync(path)) return { applied: false, reason: 'no Hermes config at ~/.hermes/config.yaml' };
-  const text = readFileSync(path, 'utf8');
-  if (/attesso.*hook/.test(text)) return { applied: false, reason: 'already wired' };
-  if (/^hooks:/m.test(text)) {
-    return { applied: false, reason: 'config already has a hooks: block, merge by hand', snippet: HOOK_BLOCK(cli, dir) };
-  }
-  const next = text.replace(/^approvals:/m, `${HOOK_BLOCK(cli, dir)}approvals:`);
-  if (next === text) return { applied: false, reason: 'no anchor to insert before; add the block by hand', snippet: HOOK_BLOCK(cli, dir) };
-  if (!dryRun) {
-    renameSync(path, `${path}.bak`);
-    writeFileSync(path, next);
-  }
-  return { applied: !dryRun, path, snippet: HOOK_BLOCK(cli, dir) };
-}
-
 export function explain(dir, seq, { entries }) {
   const entry = entries.find((candidate) => candidate.seq === Number(seq));
   if (!entry) return { found: false, seq };
-  const taintedBy = entry.meta?.tainted_by;
+  const taintedBy = entry.tainted_by ?? entry.meta?.tainted_by;
+  const rule = entry.rule ?? entry.meta?.rule ?? null;
   const source = taintedBy ? entries.find((candidate) => candidate.seq === taintedBy) : null;
+  const advice =
+    entry.decision === 'ALLOW'
+      ? 'Nothing to fix: this call was allowed.'
+      : entry.code === 'PATH_DENIED'
+        ? `The task read ${source?.subject ?? 'untrusted content'} at step #${taintedBy}. Take another path, or narrow ${rule}.`
+        : entry.code === 'STEP_LIMIT'
+          ? `The task reached the step ceiling in ${rule}. Split the task or raise the ceiling.`
+          : entry.code === 'REPEAT_LIMIT'
+            ? `The task repeated the same call past ${rule}. Change the call or raise the ceiling.`
+            : rule
+              ? `The call broke ${rule}. Check the field it names.`
+              : 'The call broke the policy, not a path rule. Check the amount, payee or window.';
   return {
     found: true,
     seq: entry.seq,
@@ -83,22 +77,17 @@ export function explain(dir, seq, { entries }) {
     trust: entry.trust,
     verdict: entry.decision,
     code: entry.code,
-    rule: entry.meta?.rule ?? null,
+    rule,
     task: entry.task ?? null,
     tainted_by: source ? { seq: source.seq, action: source.action, subject: source.subject, trust: source.trust } : null,
-    advice:
-      entry.decision === 'ALLOW'
-        ? 'Nothing to fix: this call was allowed.'
-        : entry.meta?.rule
-          ? `The task read ${source?.subject ?? 'untrusted content'} at step #${taintedBy}. Take another path, or narrow ${entry.meta.rule}.`
-          : 'The call broke the policy, not a path rule. Check the amount, payee or window.',
+    advice,
   };
 }
 
-const signature = (entry) => `${entry.action}\u0000${entry.subject ?? ''}\u0000${entry.meta?.args_hash ?? ''}`;
+const signature = (entry) => `${entry.action}\u0000${entry.subject ?? ''}\u0000${argsHashOf(entry) ?? ''}`;
 
 export function suggest(dir, { entries, minRepeats = 3 }) {
-  const within = entries.filter((entry) => entry.decision === 'ALLOW');
+  const within = entries.filter((entry) => entry.decision === 'ALLOW' && argsHashOf(entry) !== undefined);
   const counts = new Map();
   for (const entry of within) {
     const key = `${entry.task ?? ''}\u0000${signature(entry)}`;