attesso 0.3.1 → 0.4.0

package/README.md

@@ -27,6 +27,32 @@ hermes-local-9552aa28437e88c0610a…  2058     455 (22%)  PATH_DENIED×455  3,92
 
 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.
 
+## Wire it into an agent
+
+`attesso hook` speaks the shell-hook contract that Claude Code, Cursor and Hermes
+already use: one tool call on stdin, exit 2 to refuse. Start in observe mode so the
+ledger records what the rules would have refused and nothing is blocked:
+
+```sh
+node bin/attesso.mjs --dir ~/.hermes/attesso-veto/ledger hook --observe
+```
+
+Hermes config (`~/.hermes/config.yaml`), or the same shape in any harness with hooks:
+
+```yaml
+hooks:
+  pre_tool_call:
+    - command: npx attesso --dir ~/.attesso hook
+      timeout: 10
+```
+
+Drop `--observe` when the refusal rate on your own work looks right: a deny then
+exits 2 with a message the agent reads, and the step never runs.
+
+For a long-lived harness, `attesso serve` answers the same questions over one
+process: write one JSON request per line, read one verdict per line. A decision
+costs an IPC round trip instead of a process spawn.
+
 ## What it records
 
 One signed line per proposed action:

package/bin/attesso.mjs

@@ -10,6 +10,8 @@ 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';
+import { serve } from './../src/serve.mjs';
+import { decide } from './../src/hook.mjs';
 
 const argv = process.argv.slice(2);
 const dirAt = argv.indexOf('--dir');
@@ -27,6 +29,8 @@ const USAGE = `attesso: a local, signed ledger of what your agents attempted
   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
+  attesso serve [--observe]          long-lived: one JSON request per line in, one verdict out
+  attesso hook [--observe]           harness hook: reads one tool call on stdin, exits 2 to refuse
 
 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
@@ -219,6 +223,45 @@ switch (command) {
   case 'show':
     show();
     break;
+  case 'hook': {
+    requireLedger();
+    const run = decide({ append, dir: DIR, observe: rest.includes('--observe') });
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      raw += chunk;
+    });
+    process.stdin.on('end', () => {
+      let payload;
+      try {
+        payload = JSON.parse(raw || '{}');
+      } catch {
+        console.error('attesso hook: stdin was not JSON, so no decision was made');
+        process.exit(1);
+      }
+      try {
+        const result = run(payload);
+        if (result.exitCode !== 0) {
+          process.stdout.write(`${JSON.stringify({ decision: 'block', message: result.body.message, code: result.body.code })}\n`);
+          process.exit(2);
+        }
+        process.stdout.write(`${JSON.stringify({ decision: result.body.decision, code: result.body.code })}\n`);
+      } catch (error) {
+        // An unwritable ledger is an outage, not a policy decision: say so and
+        // exit 1 so a fail-closed harness can tell the two apart.
+        console.error(`attesso hook: ${error.message}`);
+        process.exit(1);
+      }
+    });
+    break;
+  }
+  case 'serve':
+    requireLedger();
+    serve(DIR, { observe: rest.includes('--observe') }).catch((error) => {
+      console.error(`attesso serve: ${error.message}`);
+      process.exit(1);
+    });
+    break;
   case 'report': {
     requireLedger();
     const report = buildReport(DIR);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "attesso",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "A local, signed ledger of what your AI agents attempted, what was allowed, and what was refused.",
   "license": "Apache-2.0",
   "type": "module",

package/src/hook.mjs

@@ -0,0 +1,65 @@
+// One decision for a harness hook. Reads the shell-hook payload on stdin
+// ({hook_event_name, tool_name, tool_input, session_id, ...}, the shape Claude
+// Code, Cursor and Hermes all use) and answers in the same contract: exit 2 with
+// a message refuses, exit 0 lets the call run.
+//
+// The mapping from a tool name to (action, capability, trust) is the only
+// harness-specific knowledge here, so every harness shares one policy engine.
+const EXECUTE = new Set(['terminal', 'execute_code', 'process_manage', 'shell', 'bash']);
+const WRITE = new Set(['write_file', 'patch', 'skill_manage', 'str_replace_editor', 'edit']);
+const UNTRUSTED_READ = new Set([
+  'browser_exec',
+  'web_search',
+  'web_extract',
+  'firecrawl',
+  'firecrawl_scrape',
+  'firecrawl_search',
+  'firecrawl_crawl',
+  'firecrawl_map',
+  'firecrawl_extract',
+  'firecrawl_deep_research',
+  'deepseek-search',
+  'ds',
+]);
+
+export function classifyTool(toolName) {
+  const name = String(toolName ?? '').trim();
+  if (UNTRUSTED_READ.has(name)) return { action: 'web.read', capability: 'read', trust: 'untrusted' };
+  if (EXECUTE.has(name)) return { action: 'shell.execute', capability: 'execute', trust: 'internal' };
+  if (WRITE.has(name)) return { action: 'file.write', capability: 'execute', trust: 'internal' };
+  if (/send|mail|post|publish/i.test(name)) return { action: 'message.send', capability: 'send', trust: 'internal' };
+  return { action: 'tool.call', capability: 'read', trust: 'internal' };
+}
+
+export function requestFromPayload(payload) {
+  const { action, capability, trust } = classifyTool(payload.tool_name);
+  return {
+    action,
+    subject: payload.tool_name ?? null,
+    task: payload.session_id ?? 'unknown',
+    trust,
+    capability,
+  };
+}
+
+export function decide({ append, dir, observe }) {
+  return (payload) => {
+    const entry = append(dir, requestFromPayload(payload));
+    const refused = entry.decision !== 'ALLOW';
+    return {
+      exitCode: refused && !observe ? 2 : 0,
+      body: {
+        // The harness obeys `decision`, so observe mode must answer allow even
+        // when the verdict is DENY: the ledger keeps the verdict, work continues.
+        decision: refused && !observe ? 'block' : 'allow',
+        verdict: entry.decision,
+        code: entry.code,
+        enforced: refused && !observe,
+        seq: entry.seq,
+        message: entry.meta?.rule
+          ? `Attesso refused ${payload.tool_name}: ${entry.code} by ${entry.meta.rule} (step #${entry.meta.tainted_by} tainted this task). Entry #${entry.seq} in the signed ledger.`
+          : `Attesso refused ${payload.tool_name}: ${entry.code}. Entry #${entry.seq} in the signed ledger.`,
+      },
+    };
+  };
+}

package/src/serve.mjs

@@ -0,0 +1,50 @@
+// A long-lived decision daemon: any harness writes one JSON request per line and
+// reads one verdict per line. The harness keeps the process for its whole
+// session, so a decision costs an IPC round trip instead of a process spawn.
+//
+// A refusal is recorded either way; `enforced` says whether the caller may
+// proceed, which is what makes observe mode trustworthy: the ledger keeps the
+// verdict, the agent keeps working.
+import { createInterface } from 'node:readline';
+import { append } from './store.mjs';
+
+const parse = (line) => {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+};
+
+export function serve(dir, { observe = false, input = process.stdin, output = process.stdout } = {}) {
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  rl.on('line', (line) => {
+    const request = parse(line);
+    if (!request) {
+      output.write(`${JSON.stringify({ error: 'request is not JSON' })}\n`);
+      return;
+    }
+    let entry;
+    try {
+      entry = append(dir, request);
+    } catch (error) {
+      // Never answer with a policy verdict when the record could not be written:
+      // an unwritable ledger is an outage, not a decision.
+      output.write(`${JSON.stringify({ id: request.id ?? null, error: String(error.message ?? error) })}\n`);
+      return;
+    }
+    output.write(
+      `${JSON.stringify({
+        id: request.id ?? null,
+        decision: entry.decision,
+        code: entry.code,
+        reason: entry.meta?.rule
+          ? `${entry.meta.rule} (tainted by step #${entry.meta.tainted_by})`
+          : null,
+        enforced: entry.decision === 'ALLOW' || observe ? false : true,
+        seq: entry.seq,
+      })}\n`,
+    );
+  });
+  return new Promise((resolve) => rl.on('close', resolve));
+}