attesso 0.0.1 → 0.3.1

package/README.md

@@ -1,31 +1,51 @@
 # attesso
 
-A local, signed ledger of what your AI agents attempted, what was allowed, and what was refused. No account, no server, no dependencies.
+A local, signed ledger of what your AI agents attempted, what was allowed, and what was refused. Any action, not only payments. No account, no server, no dependencies.
 
 ```sh
 npx attesso init
-npx attesso log --action purchase.execute --amount 12.50 --currency EUR --payee shop.example
+npx attesso log --action tool.call --subject read_file --meta tokens=1200 --meta cost_usd=0.0004
+npx attesso log --action purchase.execute --subject shop.example --amount 12.50 --currency EUR
 npx attesso verify
 npx attesso show
+npx attesso report
 ```
 
-`init` writes `.attesso/` with an Ed25519 key, a policy and an empty ledger. `log` evaluates one proposed action against the policy, records the decision and its reason, and exits 1 when it refuses. `verify` recomputes the hash chain and every signature. `show` prints what was allowed, what was refused and why.
+`init` writes `.attesso/` with an Ed25519 key, a policy and an empty ledger. `log` evaluates one proposed action against the policy, records the decision and its reason, and exits 1 when it refuses. `verify` recomputes the hash chain and every signature. `show` prints what was allowed, what was refused, which subjects dominate, and any tokens or cost you passed in `--meta`. `--dir PATH` points any command at a different ledger.
+
+## The overview
+
+`attesso report` is the view that answers what the thing cost and what it stopped, per task:
+
+```
+2059 entries, key 1qTU-tGyjuQwt3kI: 2058 actions, 455 refused (22%), 3,922,488 tokens, 3.1932 USD
+
+task                                actions  refused    top              tokens     cached       cost
+──────────────────────────────────  ───────  ─────────  ───────────────  ─────────  ───────────  ──────
+hermes-local-9552aa28437e88c0610a…  2058     455 (22%)  PATH_DENIED×455  3,922,488  645,785,088  3.1932
+```
+
+Actions are tool calls; refusals carry the reason; tokens are input plus output, with cache reads shown separately because they bill at a different rate and dwarf the rest. Cost comes from a `llm.session` entry the recorder writes from the agent's own usage record, never from a number the report invents. `--json` gives the same data for a dashboard.
 
 ## What it records
 
 One signed line per proposed action:
 
 ```json
-{"v":1,"seq":1,"at":"2026-10-31T12:00:00.000Z","action":"purchase.execute",
- "amount":{"minor":1250,"currency":"EUR"},"payee":"shop.example",
- "decision":"ALLOW","code":"ALLOW","policy_digest":"…","kid":"…","prev":"genesis","sig":"…"}
+{"v":1,"seq":1,"at":"2026-10-31T12:00:00.000Z","action":"tool.call",
+ "subject":"read_file","decision":"ALLOW","code":"ALLOW","policy_digest":"…",
+ "kid":"…","prev":"genesis","meta":{"tokens":1200,"cost_usd":0.0004},"sig":"…"}
 ```
 
-Refusal codes match the hosted engine: `ACTION_MISMATCH`, `ABOVE_MAXIMUM`, `VALUE_NOT_ALLOWED`, `VALUE_MISMATCH`, `OUTSIDE_DATE_RANGE`, `REQUIRED_ATTRIBUTE_MISSING`.
+`subject` is the thing acted on: a tool name, a payee, a repo, a recipient. `amount` appears only for money actions. Refusal codes match the hosted engine: `ACTION_MISMATCH`, `ABOVE_MAXIMUM`, `VALUE_NOT_ALLOWED`, `VALUE_MISMATCH`, `OUTSIDE_DATE_RANGE`, `REQUIRED_ATTRIBUTE_MISSING`.
 
 ## The policy
 
-`.attesso/policy.json` starts at zero, so nothing is allowed until you set it:
+`.attesso/policy.json` starts empty, so nothing is allowed until you set it. A policy governs one action; `"action": "*"` covers every action and is what a recording-only ledger uses.
+
+```json
+{ "version": 1, "action": "tool.call", "subjects": ["read_file", "search_files", "grep_repo"] }
+```
 
 ```json
 {
@@ -33,21 +53,61 @@ Refusal codes match the hosted engine: `ACTION_MISMATCH`, `ABOVE_MAXIMUM`, `VALU
   "action": "purchase.execute",
   "currency": "EUR",
   "max_amount": 25000,
-  "payees": ["shop.example"],
+  "subjects": ["shop.example"],
   "on_or_after": "2026-11-01T00:00:00Z",
   "on_or_before": "2026-12-01T00:00:00Z"
 }
 ```
 
-Amounts are whole minor units in the policy (25000 = 250.00 EUR); `log --amount` takes the decimal form.
+Money is optional: without `max_amount` and `currency` the policy is judged on action, subject and window alone. Amounts in the policy are whole minor units (25000 = 250.00 EUR); `log --amount` takes the decimal form.
+
+## Policies on paths
+
+A single step can look fine and the sequence still be wrong: reading an untrusted page and then sending it somewhere is an exfiltration no per-step check can see. `attesso` judges an action against the path of its task, not in isolation. Three flags give it the shape of the step, and `.attesso/rules.json` says what a path may not do.
+
+```sh
+npx attesso log --action web.read   --subject docs.example         --task job-1 --trust untrusted --capability read
+npx attesso log --action mail.send  --subject partner@example.com  --task job-1 --capability send
+# #2 DENY mail.send partner@example.com (PATH_DENIED by step #1 under no-send-after-untrusted-read)
+
+npx attesso log --action file.read  --subject src/app.ts           --task job-2 --trust internal  --capability read
+npx attesso log --action mail.send  --subject partner@example.com  --task job-2 --capability send
+# #4 ALLOW mail.send partner@example.com (ALLOW)
+```
+
+`init` ships one rule, and it is the one worth having:
+
+```json
+{ "version": 1,
+  "rules": [
+    { "id": "no-send-after-untrusted-read",
+      "deny": { "capabilities": ["send", "execute"] },
+      "if_path": { "trust": "untrusted", "capability": "read", "within_minutes": 30 } }
+  ] }
+```
+
+`--task` scopes the history, so one job cannot taint another. `within_minutes` limits how long a read stays relevant; without it a taint lasts for the whole task. `--capability` is one of `read`, `send`, `execute`, `spend`. The refusal names the rule and the step that tainted the path, so a reader can see the sequence rather than a verdict.
+
+Rules are ordinary files you own and version. Run them in observe mode first: `node scripts/hermes-ledger.mjs --observe` records what the rules would have refused without touching the agent, which is how you learn where a rule is too broad before it costs you a day.
+
+## Recording a real agent
+
+`attesso` is a CLI, so anything that can run a command can record an action. To see what a Hermes session actually did, the repo ships `scripts/hermes-ledger.mjs`, which reads a session from `state.db` read-only and appends one entry per tool call.
+
+```sh
+node scripts/hermes-ledger.mjs --dir .hermes/tmp/attesso-dogfood --observe
+npx attesso --dir .hermes/tmp/attesso-dogfood show
+```
+
+`--observe` labels every verdict the rules produced and prints how many steps they would have refused; nothing in the agent is blocked. Tool calls are classified on the way in: `read_file` and the repo search tools read internal material, the web and browser tools read untrusted material, and anything that writes, executes or spawns is an effect.
 
 ## What this proves, and what it does not
 
 The signature proves the ledger was not edited after the fact: change one byte and `verify` names the entry, reorder two and the chain breaks, delete the last one and the recorded head no longer matches.
 
-It does not prove a human authorized anything. The signing key lives in `.attesso/key.json`, in the same directory as the log, so anything that can write the log can also write a new one. It also cannot see absence: a process that deletes the whole directory leaves nothing to verify.
+It does not prove a human authorized anything. The signing key lives in `.attesso/key.json`, in the same directory as the log, so anything that can write the log can also write a new one. It cannot see absence either: a process that deletes the whole directory leaves nothing to verify.
 
-Hosted Attesso is where authority lives: a passkey approval binds a named human to exact terms, the decision and the refusal are recorded server-side, and the result is evidence a third party verifies offline against a published key. The local ledger uses the same event shape, so it can be submitted there later.
+Hosted Attesso is where authority lives: a passkey approval binds a named human to exact terms, the decision and the refusal are recorded server-side, and the result is evidence a third party verifies offline against a published key. The local ledger uses the same event and code vocabulary, so it can be submitted there later.
 
 ## Exit codes
 

package/bin/attesso.mjs

@@ -2,22 +2,38 @@
 // attesso: a local, signed ledger of what your agents attempted.
 //
 //   attesso init
-//   attesso log --action purchase.execute --amount 12.50 --currency EUR --payee shop.example
+//   attesso log --action tool.call --subject read_file --meta tokens=1200 --meta cost_usd=0.0004
+//   attesso log --action purchase.execute --subject shop.example --amount 12.50 --currency EUR
 //   attesso verify
 //   attesso show
 import { verifyChain } from './../src/ledger.mjs';
 import { formatMinor, toMinor } from './../src/policy.mjs';
 import { append, init, isInitialised, paths, readState } from './../src/store.mjs';
+import { buildReport, renderReport } from './../src/report.mjs';
 
-const DIR = '.attesso';
+const argv = process.argv.slice(2);
+const dirAt = argv.indexOf('--dir');
+const DIR = dirAt === -1 ? '.attesso' : argv[dirAt + 1];
+if (dirAt !== -1) argv.splice(dirAt, 2);
 
 const USAGE = `attesso: a local, signed ledger of what your agents attempted
 
-  attesso init                       create .attesso with a key and a policy
-  attesso log --action A --amount 12.50 --currency EUR [--payee P] [--json]
-                                     evaluate one proposed action and record it
+  attesso init [--dir PATH]          create .attesso with a key and a policy
+  attesso log --action A [--subject S] [--amount 12.50 --currency EUR]
+              [--task T] [--trust internal|untrusted] [--capability read|send|execute|spend]
+              [--meta k=v ...] [--json]
+                                     evaluate one proposed action against the policy
+                                     and the path of its task, then record it
   attesso verify                     recompute the chain and report the first defect
   attesso show                       what was allowed, what was refused, and why
+  attesso report [--json]            per task: actions, refusals with reasons, tokens and cost
+
+Any action can be logged, not only payments. --subject is the thing acted on (a
+tool name, a payee, a repo). --task scopes the path, --trust marks where the
+content came from, and --capability says what the step does; with those three, a
+rule in .attesso/rules.json can refuse a send that follows an untrusted read,
+which no per-step check can see. --meta carries whatever you want counted later
+(tokens, cost_usd, duration_ms, model).
 
 The log is signed with a key that lives in .attesso/key.json. That proves the
 ledger was not edited; it does not prove a human authorized anything. Hosted
@@ -34,12 +50,28 @@ function flags(argv) {
       out[name] = true;
       continue;
     }
-    out[name] = next;
+    if (name === 'meta') {
+      out.meta = [...(out.meta ?? []), next];
+    } else {
+      out[name] = next;
+    }
     index += 1;
   }
   return out;
 }
 
+function parseMeta(pairs = []) {
+  const meta = {};
+  for (const pair of pairs) {
+    const at = pair.indexOf('=');
+    if (at <= 0) throw new Error(`--meta expects key=value, got ${pair}`);
+    const key = pair.slice(0, at);
+    const raw = pair.slice(at + 1);
+    meta[key] = raw !== '' && !Number.isNaN(Number(raw)) ? Number(raw) : raw;
+  }
+  return meta;
+}
+
 function requireLedger() {
   if (!isInitialised(DIR)) {
     console.error(`no ledger at ${paths(DIR).dir}; run attesso init first`);
@@ -47,24 +79,63 @@ function requireLedger() {
   }
 }
 
+function describe(entry) {
+  const subject = entry.subject ? ` ${entry.subject}` : '';
+  const amount = entry.amount ? ` ${formatMinor(entry.amount.minor, entry.amount.currency)} ${entry.amount.currency}` : '';
+  return `${entry.action}${subject}${amount}`;
+}
+
 function log(argv) {
   requireLedger();
   const options = flags(argv);
-  for (const required of ['action', 'amount', 'currency']) {
-    if (typeof options[required] !== 'string') {
-      console.error(`attesso log needs --${required}`);
-      process.exit(2);
+  if (typeof options.action !== 'string') {
+    console.error('attesso log needs --action');
+    process.exit(2);
+  }
+  if ((options.amount === undefined) !== (options.currency === undefined)) {
+    console.error('--amount and --currency go together');
+    process.exit(2);
+  }
+  let amount;
+  if (options.amount !== undefined) {
+    try {
+      amount = { minor: toMinor(options.amount, options.currency), currency: options.currency };
+    } catch (error) {
+      console.error(error.message);
+      process.exit(1);
     }
   }
-  const amount = { minor: toMinor(options.amount, options.currency), currency: options.currency };
-  const entry = append(DIR, { action: options.action, amount, payee: options.payee });
+  let meta;
+  try {
+    meta = parseMeta(options.meta);
+  } catch (error) {
+    console.error(error.message);
+    process.exit(2);
+  }
+
+  if (options.trust !== undefined && !['internal', 'untrusted', 'unknown'].includes(options.trust)) {
+    console.error('--trust takes internal, untrusted or unknown');
+    process.exit(2);
+  }
+  if (options.capability !== undefined && !['read', 'send', 'execute', 'spend'].includes(options.capability)) {
+    console.error('--capability takes read, send, execute or spend');
+    process.exit(2);
+  }
+  const entry = append(DIR, {
+    action: options.action,
+    subject: options.subject,
+    amount,
+    meta,
+    task: typeof options.task === 'string' ? options.task : undefined,
+    trust: options.trust,
+    capability: options.capability,
+  });
   if (options.json) {
     console.log(JSON.stringify(entry));
     return;
   }
-  const human = `${formatMinor(entry.amount.minor, entry.amount.currency)} ${entry.amount.currency}`;
-  const subject = entry.payee ? ` at ${entry.payee}` : '';
-  console.log(`#${entry.seq} ${entry.decision} ${entry.action} ${human}${subject} (${entry.code})`);
+  const taint = entry.meta?.tainted_by === undefined ? '' : ` by step #${entry.meta.tainted_by} under ${entry.meta.rule}`;
+  console.log(`#${entry.seq} ${entry.decision} ${describe(entry)} (${entry.code}${taint})`);
   process.exitCode = entry.decision === 'ALLOW' ? 0 : 1;
 }
 
@@ -79,6 +150,17 @@ function verify() {
   console.log(`ledger verifies: ${result.reason}, key ${state.key.kid}`);
 }
 
+function totals(entries) {
+  const sum = (field) =>
+    entries.reduce((total, entry) => total + (Number(entry.meta?.[field]) || 0), 0);
+  const tokens = sum('tokens');
+  const cost = sum('cost_usd');
+  const parts = [];
+  if (tokens > 0) parts.push(`${tokens.toLocaleString('en-US')} tokens`);
+  if (cost > 0) parts.push(`${cost.toFixed(4)} USD`);
+  return parts.length > 0 ? `, ${parts.join(', ')}` : '';
+}
+
 function show() {
   requireLedger();
   const { entries, key } = readState(DIR);
@@ -92,25 +174,36 @@ function show() {
     counts.set(label, (counts.get(label) ?? 0) + 1);
   }
   const allowed = entries.filter((entry) => entry.decision === 'ALLOW').length;
-  console.log(`${entries.length} decisions: ${allowed} allowed, ${entries.length - allowed} refused (key ${key.kid})`);
+  console.log(
+    `${entries.length} decisions: ${allowed} allowed, ${entries.length - allowed} refused${totals(entries)} (key ${key.kid})`,
+  );
   for (const [label, count] of [...counts.entries()].sort()) {
     console.log(`  ${String(count).padStart(4)}  ${label}`);
   }
-  const last = entries.slice(-5);
+  const bySubject = new Map();
+  for (const entry of entries) {
+    const label = entry.subject ?? '(none)';
+    bySubject.set(label, (bySubject.get(label) ?? 0) + 1);
+  }
+  if (bySubject.size > 0 && [...bySubject.keys()].some((label) => label !== '(none)')) {
+    console.log('subjects:');
+    for (const [label, count] of [...bySubject.entries()].sort((left, right) => right[1] - left[1])) {
+      console.log(`  ${String(count).padStart(4)}  ${label}`);
+    }
+  }
   console.log('latest:');
-  for (const entry of last) {
-    const human = `${formatMinor(entry.amount.minor, entry.amount.currency)} ${entry.amount.currency}`;
-    console.log(`  #${entry.seq} ${entry.at} ${entry.decision} ${entry.action} ${human} (${entry.code})`);
+  for (const entry of entries.slice(-5)) {
+    console.log(`  #${entry.seq} ${entry.at} ${entry.decision} ${describe(entry)} (${entry.code})`);
   }
 }
 
-const [command, ...rest] = process.argv.slice(2);
+const [command, ...rest] = argv;
 switch (command) {
   case 'init': {
     try {
       const result = init(DIR);
       console.log(`created ${result.dir} with key ${result.kid}`);
-      console.log('edit .attesso/policy.json to set what is allowed (it starts at zero)');
+      console.log('edit .attesso/policy.json to set what is allowed (it starts at nothing)');
     } catch (error) {
       console.error(error.message);
       process.exit(1);
@@ -126,6 +219,16 @@ switch (command) {
   case 'show':
     show();
     break;
+  case 'report': {
+    requireLedger();
+    const report = buildReport(DIR);
+    if (rest.includes('--json')) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      process.stdout.write(renderReport(report));
+    }
+    break;
+  }
   case undefined:
     console.log(USAGE);
     break;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "attesso",
-  "version": "0.0.1",
+  "version": "0.3.1",
   "description": "A local, signed ledger of what your AI agents attempted, what was allowed, and what was refused.",
   "license": "Apache-2.0",
   "type": "module",
@@ -16,7 +16,8 @@
     "node": ">=20"
   },
   "scripts": {
-    "test": "node --test test"
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "node --test test/*.test.mjs"
   },
   "keywords": [
     "ai-agents",

package/src/ledger.mjs

@@ -39,20 +39,25 @@ export function verifyEntry(entry, publicPem) {
   return verify(null, signingPayload(entry), publicPem, Buffer.from(entry.sig, 'base64url'));
 }
 
-export function buildEntry({ seq, prev, action, amount, payee, decision, code, policyDigest, kid, at }) {
-  return {
+export function buildEntry({ seq, prev, action, subject, amount, meta, task, trust, capability, decision, code, policyDigest, kid, at }) {
+  const entry = {
     v: ENTRY_VERSION,
     seq,
     at: at ?? new Date().toISOString(),
     action,
-    amount,
-    payee: payee ?? null,
+    subject: subject ?? null,
     decision,
     code,
     policy_digest: policyDigest,
     kid,
     prev,
   };
+  if (amount) entry.amount = amount;
+  if (task) entry.task = task;
+  if (trust) entry.trust = trust;
+  if (capability) entry.capability = capability;
+  if (meta && Object.keys(meta).length > 0) entry.meta = meta;
+  return entry;
 }
 
 // Returns the first defect rather than a boolean, so a reader learns which entry

package/src/policy.mjs

@@ -1,7 +1,7 @@
-// Deterministic local policy. Same code names the hosted engine returns, so a
-// local refusal reads the same as a server one when the log is exported.
-import { canonical } from './canonical.mjs';
+// Deterministic local policy, for any agent action, money or not. Codes match
+// the hosted engine so a local refusal reads the same as a server one.
 import { createHash } from 'node:crypto';
+import { canonical } from './canonical.mjs';
 
 export const ALLOW = 'ALLOW';
 
@@ -30,6 +30,8 @@ export function policyDigest(policy) {
   return createHash('sha256').update(canonical(policy)).digest('base64url');
 }
 
+// A policy is about one action. Money is optional: an action like tool.call or
+// repo.write has bounds but no amount, and saying so with max_amount is wrong.
 export function validatePolicy(policy) {
   const fail = (message) => {
     throw new Error(`policy is invalid: ${message}`);
@@ -37,13 +39,18 @@ export function validatePolicy(policy) {
   if (policy === null || typeof policy !== 'object') fail('not an object');
   if (policy.version !== 1) fail('version must be 1');
   if (typeof policy.action !== 'string' || policy.action === '') fail('action must be a non-empty string');
-  if (!EXPONENTS[policy.currency]) fail(`currency ${policy.currency} is not supported`);
-  if (!Number.isInteger(policy.max_amount) || policy.max_amount < 0) {
-    fail('max_amount must be a whole number of minor units, 0 or more');
+  if (policy.action !== '*' && policy.action.trim() === '') fail('action must be a non-empty string or *');
+
+  const money = policy.max_amount !== undefined || policy.currency !== undefined;
+  if (money) {
+    if (!EXPONENTS[policy.currency]) fail(`currency ${policy.currency} is not supported`);
+    if (!Number.isInteger(policy.max_amount) || policy.max_amount < 0) {
+      fail('max_amount must be a whole number of minor units, 0 or more');
+    }
   }
-  if (policy.payees !== undefined) {
-    if (!Array.isArray(policy.payees) || policy.payees.some((payee) => typeof payee !== 'string' || payee === '')) {
-      fail('payees must be a list of non-empty strings when present');
+  if (policy.subjects !== undefined) {
+    if (!Array.isArray(policy.subjects) || policy.subjects.some((item) => typeof item !== 'string' || item === '')) {
+      fail('subjects must be a list of non-empty strings when present');
     }
   }
   for (const field of ['on_or_after', 'on_or_before']) {
@@ -57,20 +64,27 @@ export function validatePolicy(policy) {
 // Order matters for the reader: the most specific reason wins, so a refusal
 // names one cause rather than a list.
 export function evaluate(policy, proposal, now = new Date()) {
-  if (proposal.action !== policy.action) {
+  if (policy.action !== '*' && proposal.action !== policy.action) {
     return { decision: 'DENY', code: 'ACTION_MISMATCH' };
   }
-  if (!proposal.amount || !Number.isInteger(proposal.amount.minor)) {
-    return { decision: 'DENY', code: 'REQUIRED_ATTRIBUTE_MISSING' };
-  }
-  if (proposal.amount.currency !== policy.currency) {
-    return { decision: 'DENY', code: 'VALUE_MISMATCH' };
-  }
-  if (policy.payees && !policy.payees.includes(proposal.payee)) {
-    return { decision: 'DENY', code: 'VALUE_NOT_ALLOWED' };
+  if (policy.subjects !== undefined) {
+    if (typeof proposal.subject !== 'string') {
+      return { decision: 'DENY', code: 'REQUIRED_ATTRIBUTE_MISSING' };
+    }
+    if (!policy.subjects.includes(proposal.subject)) {
+      return { decision: 'DENY', code: 'VALUE_NOT_ALLOWED' };
+    }
   }
-  if (proposal.amount.minor > policy.max_amount) {
-    return { decision: 'DENY', code: 'ABOVE_MAXIMUM' };
+  if (policy.max_amount !== undefined) {
+    if (!proposal.amount || !Number.isInteger(proposal.amount.minor)) {
+      return { decision: 'DENY', code: 'REQUIRED_ATTRIBUTE_MISSING' };
+    }
+    if (proposal.amount.currency !== policy.currency) {
+      return { decision: 'DENY', code: 'VALUE_MISMATCH' };
+    }
+    if (proposal.amount.minor > policy.max_amount) {
+      return { decision: 'DENY', code: 'ABOVE_MAXIMUM' };
+    }
   }
   const at = now.getTime();
   if (policy.on_or_after && at < Date.parse(policy.on_or_after)) {

package/src/report.mjs

@@ -0,0 +1,76 @@
+// The overview that answers "what did this actually cost me, and what did it
+// 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';
+
+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);
+  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'),
+  };
+}
+
+export function buildReport(dir) {
+  const { entries, key } = readState(dir);
+  const groups = new Map();
+  for (const entry of entries) {
+    const task = entry.task ?? '(unscoped)';
+    if (!groups.has(task)) groups.set(task, []);
+    groups.get(task).push(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 };
+}
+
+const percent = (share) => (share === null ? 'n/a' : `${Math.round(share * 100)}%`);
+
+export function renderReport(report) {
+  const lines = [];
+  lines.push(
+    `${report.entries} entries, key ${report.key}: ${report.totals.actions} actions, ` +
+      `${report.totals.blocked} refused (${percent(report.totals.blocked_share)}), ` +
+      `${report.totals.tokens.toLocaleString('en-US')} tokens, ${report.totals.cost_usd.toFixed(4)} USD`,
+  );
+  lines.push('');
+  const rows = report.tasks.map((task) => ({
+    task: task.task.length > 34 ? `${task.task.slice(0, 33)}…` : task.task,
+    actions: String(task.actions),
+    refused: `${task.blocked} (${percent(task.blocked_share)})`,
+    top: task.reasons.slice(0, 2).map((reason) => `${reason.code}×${reason.count}`).join(' '),
+    tokens: task.tokens.toLocaleString('en-US'),
+    cached: task.cached_tokens > 0 ? task.cached_tokens.toLocaleString('en-US') : '',
+    cost: task.cost_usd > 0 ? task.cost_usd.toFixed(4) : '',
+  }));
+  const width = (field) => Math.max(field.length, ...rows.map((row) => String(row[field]).length));
+  const columns = ['task', 'actions', 'refused', 'top', 'tokens', 'cached', 'cost'];
+  const sizes = Object.fromEntries(columns.map((column) => [column, width(column)]));
+  const header = columns.map((column) => column.padEnd(sizes[column])).join('  ');
+  lines.push(header);
+  lines.push(columns.map((column) => '─'.repeat(sizes[column])).join('  '));
+  for (const row of rows) {
+    lines.push(columns.map((column) => String(row[column]).padEnd(sizes[column])).join('  '));
+  }
+  return `${lines.join('\n')}\n`;
+}

package/src/rules.mjs

@@ -0,0 +1,65 @@
+// Policies on paths: an action is judged against the ordered history of the same
+// task, not in isolation. A read of something untrusted followed by a send is the
+// case no per-step check can catch, and it is the reason this file exists.
+import { createHash } from 'node:crypto';
+import { canonical } from './canonical.mjs';
+
+export const CAPABILITIES = ['read', 'send', 'execute', 'spend'];
+export const TRUST_LEVELS = ['internal', 'untrusted', 'unknown'];
+
+export function rulesDigest(rules) {
+  return createHash('sha256').update(canonical(rules)).digest('base64url');
+}
+
+export function validateRules(rules) {
+  const fail = (message) => {
+    throw new Error(`rules are invalid: ${message}`);
+  };
+  if (rules === null || typeof rules !== 'object') fail('not an object');
+  if (rules.version !== 1) fail('version must be 1');
+  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.capabilities ?? (deny.capability ? [deny.capability] : []);
+    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}`);
+    }
+    const trigger = rule.if_path ?? {};
+    if (trigger.trust && !TRUST_LEVELS.includes(trigger.trust)) fail(`rule ${rule.id} names unknown trust ${trigger.trust}`);
+    if (trigger.capability && !CAPABILITIES.includes(trigger.capability)) {
+      fail(`rule ${rule.id} triggers on unknown capability ${trigger.capability}`);
+    }
+    if (trigger.trust === undefined && trigger.capability === undefined) {
+      fail(`rule ${rule.id} has no path condition`);
+    }
+    if (trigger.within_minutes !== undefined && (!Number.isInteger(trigger.within_minutes) || trigger.within_minutes < 0)) {
+      fail(`rule ${rule.id} needs whole minutes for within_minutes`);
+    }
+  }
+  return rules;
+}
+
+// The most recent matching step taints the path; naming it is what makes the
+// refusal explainable rather than mysterious.
+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.capabilities ?? (deny.capability ? [deny.capability] : []);
+    if (proposal.capability && !denied.includes(proposal.capability)) continue;
+    const trigger = rule.if_path ?? {};
+    const window = (trigger.within_minutes ?? 0) * 60_000;
+    const hit = [...history].reverse().find((entry) => {
+      if (trigger.trust && entry.trust !== trigger.trust) return false;
+      if (trigger.capability && entry.capability !== trigger.capability) return false;
+      if (window > 0 && now.getTime() - Date.parse(entry.at) > window) return false;
+      return true;
+    });
+    if (hit) {
+      return { decision: 'DENY', code: 'PATH_DENIED', rule: rule.id, tainted_by: hit.seq };
+    }
+  }
+  return null;
+}

package/src/store.mjs

@@ -9,12 +9,14 @@ import { closeSync, existsSync, mkdirSync, openSync, readFileSync, renameSync, u
 import { join } from 'node:path';
 import { buildEntry, entryHash, newSigningKey, signEntry } from './ledger.mjs';
 import { evaluate, policyDigest, validatePolicy } from './policy.mjs';
+import { evaluatePath, rulesDigest, validateRules } from './rules.mjs';
 
 export function paths(dir) {
   return {
     dir,
     key: join(dir, 'key.json'),
     policy: join(dir, 'policy.json'),
+    rules: join(dir, 'rules.json'),
     ledger: join(dir, 'ledger.jsonl'),
     config: join(dir, 'config.json'),
     lock: join(dir, 'lock'),
@@ -41,13 +43,20 @@ export function init(dir) {
   const file = paths(dir);
   const key = newSigningKey();
   writeJson(file.key, { version: 1, kid: key.kid, public: key.publicPem, private: key.privatePem });
+  // Record everything by default and let rules.json decide: a policy that names
+  // one action refuses every other action, so a fresh install could not log the
+  // very commands its own README shows.
   writeJson(file.policy, {
     version: 1,
-    action: 'EXAMPLE.action',
-    currency: 'EUR',
-    max_amount: 0,
+    action: '*',
   });
   writeJson(file.config, { version: 1, head: { count: 0, hash: 'genesis' } });
+  writeJson(file.rules, {
+    version: 1,
+    rules: [
+      { id: 'no-send-after-untrusted-read', deny: { capabilities: ['send', 'execute'] }, if_path: { trust: 'untrusted', capability: 'read' } },
+    ],
+  });
   writeFileSync(file.ledger, '', { mode: 0o600 });
   return { dir, kid: key.kid };
 }
@@ -58,6 +67,7 @@ export function readState(dir) {
     key: readJson(file.key),
     config: readJson(file.config),
     policy: readJson(file.policy),
+    rules: existsSync(file.rules) ? readJson(file.rules) : null,
     entries: readEntries(dir),
   };
 }
@@ -117,14 +127,27 @@ export function append(dir, proposal, { now = new Date() } = {}) {
     const key = readJson(file.key);
     const config = readJson(file.config);
     const policy = validatePolicy(readJson(file.policy));
-    const verdict = evaluate(policy, proposal, now);
+    const rules = existsSync(file.rules) ? validateRules(readJson(file.rules)) : null;
+    const history = readEntries(dir).filter((entry) => (entry.task ?? null) === (proposal.task ?? null));
+    const policyVerdict = evaluate(policy, proposal, now);
+    const pathVerdict = policyVerdict.decision === 'ALLOW'
+      ? evaluatePath(rules, history, proposal, now)
+      : null;
+    const verdict = pathVerdict ?? policyVerdict;
+    const meta = pathVerdict?.tainted_by === undefined
+      ? proposal.meta
+      : { ...(proposal.meta ?? {}), rule: pathVerdict.rule, tainted_by: pathVerdict.tainted_by };
     const seq = config.head.count + 1;
     const entry = buildEntry({
       seq,
       prev: config.head.hash,
       action: proposal.action,
+      subject: proposal.subject,
       amount: proposal.amount,
-      payee: proposal.payee,
+      meta,
+      task: proposal.task,
+      trust: proposal.trust,
+      capability: proposal.capability,
       decision: verdict.decision,
       code: verdict.code,
       policyDigest: policyDigest(policy),