codehere 2.0.0-beta.0 → 2.0.0-beta.1

package/README.md

@@ -23,12 +23,14 @@ Codehere is built to remove work, not add it. You keep using Claude Code as usua
 ```bash
 npm install -g codehere@next   # the 2.0 beta; codehere@latest is still 1.x
 cd your-project
-codehere init               # finds your test command, adds hooks to .claude/settings.json
+codehere init               # finds your test command, adds hooks to .claude/settings.json, asks you to approve the command
 git add .codehere .claude/settings.json .gitignore
 git commit -m "Add Codehere" && git push
 ```
 
-Each teammate installs the CLI once (`npm install -g codehere@next`). The hooks and the brain arrive through git.
+Each teammate installs the CLI once (`npm install -g codehere@next`) and runs `codehere approve` once in the repo. Until they do, their agent tells them at session start that the test check is off. The hooks and the brain arrive through git.
+
+The test command is in `.codehere/config.json`, which anyone with push access can change. So Codehere runs it only after you approve that exact command on your machine, at your terminal. If a pull or the agent changes it, the finish check skips it and tells you, until you approve it again. Approvals are kept in `~/.config/codehere/approvals.json`, outside the repo, so nothing that arrives through git can approve a command.
 
 ## The team loop
 
@@ -45,7 +47,17 @@ codehere reply <id> "Use price * qty; same bug was in checkout.js" --solved
 git add .codehere && git commit -m "answer" && git push
 ```
 
-`--solved` turns the answer into a **team lesson**. From then on, any teammate's agent that hits a similar error gets that fix automatically. When an agent solves a repeated error by itself, Codehere asks it to write a short lesson too.
+`--solved` turns the answer into a **team lesson**. From then on, any teammate's agent that hits a similar error gets that fix automatically. When an agent solves a repeated error by itself, Codehere saves a lesson with the proof from that test run (command, exit code, commit, the files the fix changed) and asks the agent to fill in the cause and the fix.
+
+You see one line per event:
+
+```
+codehere › Ana's lesson given to the agent · verified on Ana's machine · 21 Oct
+codehere ✕ npm test · 2 failed · agent sent back · 1 of 3
+codehere ✓ npm test · 48 passed · re-run here · 6.2 s
+```
+
+✓ marks only a test run Codehere just made on your machine. A teammate's "verified" is plain text: it was true on their machine, and anyone with push access can edit a lesson file. The agent is told whether the files the fix changed have changed since.
 
 Don't want to commit help cards? Copy the printed text into WhatsApp, Discord or Slack instead.
 
@@ -53,6 +65,7 @@ Don't want to commit help cards? Copy the printed text into WhatsApp, Discord or
 
 ```
 codehere init [--test "npm test"]       set up (safe to run again)
+codehere approve                        let the finish check run the test command on this machine
 codehere rule ["text"]                  add or list team rules
 codehere lesson ["problem" --fix "..."] add or list lessons
 codehere brief [--gemma]                restart brief for a fresh session
@@ -73,7 +86,7 @@ codehere stats                          turns to green, loops stopped, context s
   help/           help cards
   briefs/         restart briefs
   config.json     test command, loop threshold
-  local/          this machine only, git-ignored
+  local/          this machine only, git-ignored (session state)
 ```
 
 Everything is plain markdown, so you can read, edit, review and delete it like any other file.
@@ -100,9 +113,13 @@ npm test                    # end-to-end checks
 ## Known limits (2.0.0, not released yet)
 
 - Claude Code only for now. Gemini CLI and Codex hooks are next.
-- Lessons match by error text. Very generic errors can bring up a lesson that doesn't fit, which is why the agent is told it "may apply".
+- Lessons match by error text. Very generic errors can bring up a lesson that doesn't fit, which is why the agent gets it as reference, not as an instruction.
 - Redaction catches common keys, tokens and emails. Always read a help card before sharing it.
 - The "done" check needs a test command. Without one, only the tampering check runs.
+- Approvals are per folder. Each git worktree or extra clone needs its own `codehere approve`.
+- Approving `npm test` approves that command, not the scripts behind it in `package.json`. And Claude Code runs any hook a teammate adds to the committed `.claude/settings.json`. Both are your repo's code, with the same trust as running it yourself.
+- When the agent changes `.codehere/config.json`, `.codehere/rules.md` or the hook and env settings in `.claude/settings*.json` during a session, the finish check tells you. It cannot tell you if the session ends without a finish check, for example when you close it mid-turn. An agent that sets out to fake your terminal or rewrite Codehere's local files can also get around this.
+- Only the test command needs approval. A teammate who sets `verifyOnStop` to `false` in `.codehere/config.json` turns the finish check off for everyone; `codehere status` shows it as off.
 - Sharing is through git. There is no server, so teammates see updates after `git pull`.
 - Prompt checks are plain word lists (English and Indonesian). They can miss a short prompt in another language.
 - The weakened-test scan catches skipped tests, deleted test files and removed assertions. It does not yet catch an edited expected value; see `docs/overlap-with-check.md`.

package/bin/codehere.js

@@ -24,6 +24,7 @@ const USAGE = `codehere · a git-native team brain for vibe coders
 
 Setup
   codehere init [--test "npm test"]   set up .codehere/ and Claude Code hooks
+  codehere approve                    let the finish check run the test command on this machine
 
 Team brain
   codehere rule ["text"]              add a team rule (or list rules)
@@ -52,6 +53,8 @@ const run = async () => {
       return runHook(rest[0]);
     case 'init':
       return cmd.init(flags);
+    case 'approve':
+      return cmd.approve();
     case 'rule':
     case 'rules':
       return cmd.rule(rest.join(' '));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codehere",
-  "version": "2.0.0-beta.0",
+  "version": "2.0.0-beta.1",
   "description": "A git-native team brain for vibe coders. Silent fixes for AI coding agents: breaks doom loops, verifies 'done', blocks test tampering, and shares what your team learned.",
   "repository": {
     "type": "git",

package/src/brain.js

@@ -1,8 +1,9 @@
 // The team brain: plain markdown files in .codehere/, committed to git.
 // Local, per-machine state lives in .codehere/local/ (git-ignored).
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import { execSync } from 'node:child_process';
+import { execSync, execFileSync } from 'node:child_process';
 
 export function findRoot(start = process.cwd()) {
   let dir = path.resolve(start);
@@ -62,10 +63,11 @@ export function writeConfig(root, cfg) {
 
 export function readState(root) {
   try {
-    return JSON.parse(fs.readFileSync(paths(root).state, 'utf8'));
-  } catch {
-    return { sessions: {}, lastSession: null, lastGreen: null, pendingBrief: null };
-  }
+    const state = JSON.parse(fs.readFileSync(paths(root).state, 'utf8'));
+    // state.json can arrive through git: a file of the wrong shape counts as empty
+    if (state && state.sessions && typeof state.sessions === 'object') return state;
+  } catch {}
+  return { sessions: {}, lastSession: null, lastGreen: null, pendingBrief: null };
 }
 
 export function writeState(root, state) {
@@ -165,18 +167,141 @@ export function readRules(root) {
     .map((l) => l.slice(2).trim());
 }
 
+// ---------- approved test commands (this machine only) ----------
+// config.json travels through git, so a teammate's commit can change the test
+// command. The finish check runs only a command approved on this machine. The
+// approvals live outside the repo: any file in .codehere/, even a git-ignored one
+// (git add -f), can arrive through a pull.
+
+// The real path of p, for a p that may not exist yet.
+function realish(p) {
+  try {
+    return fs.realpathSync(p);
+  } catch {
+    const parent = path.dirname(p);
+    return parent === p ? p : path.join(realish(parent), path.basename(p));
+  }
+}
+
+function repoKey(root) {
+  return realish(path.resolve(root));
+}
+
+// null when the file would be inside the repo: settings committed to the repo can set
+// XDG_CONFIG_HOME or HOME for the agent's processes, and so for these hooks.
+function approvalsFile(root) {
+  const xdg = process.env.XDG_CONFIG_HOME;
+  const base = xdg && path.isAbsolute(xdg) ? xdg : path.join(os.homedir(), '.config');
+  const file = path.join(base, 'codehere', 'approvals.json');
+  return realish(file).startsWith(repoKey(root) + path.sep) ? null : file;
+}
+
+function readAllApprovals(root) {
+  try {
+    const all = JSON.parse(fs.readFileSync(approvalsFile(root), 'utf8'));
+    return all && all.repos && typeof all.repos === 'object' ? all : { repos: {} };
+  } catch {
+    return { repos: {} };
+  }
+}
+
+export function readApprovals(root) {
+  const list = readAllApprovals(root).repos[repoKey(root)]?.commands;
+  return Array.isArray(list) ? list : [];
+}
+
+export function isApproved(root, command) {
+  return readApprovals(root).some((a) => a.command === command);
+}
+
+// false when the approvals file would be inside the repo
+export function addApproval(root, command) {
+  const file = approvalsFile(root);
+  if (!file) return false;
+  const all = readAllApprovals(root);
+  const list = readApprovals(root).filter((a) => a.command !== command);
+  list.push({ command, by: me(root), at: new Date().toISOString() });
+  all.repos[repoKey(root)] = { commands: list };
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(all, null, 2) + '\n');
+  return true;
+}
+
+// Control, format (bidi, zero-width), filler and variation characters escaped, so text from the repo cannot print a fake
+// line, move the cursor or hide part of a command.
+const ESCAPES = { '\n': '\\n', '\r': '\\r', '\t': '\\t' };
+export function printable(text) {
+  return String(text).replace(
+    /[\p{Cc}\p{Cf}\u034f\u115f\u1160\u2028\u2029\u3164\ufe00-\ufe0f\u{e0100}-\u{e01ef}]/gu,
+    (c) => {
+      const n = c.codePointAt(0).toString(16);
+      return ESCAPES[c] || (n.length > 4 ? `\\u{${n}}` : `\\u${n.padStart(4, '0')}`);
+    }
+  );
+}
+
 // ---------- git helpers (all fail-safe) ----------
 
-export function git(root, args) {
+// Pass an array whenever an argument comes from the repo or the state file: it never
+// goes through a shell, so a file name such as a$(cmd).js stays a file name.
+// raw keeps the output as git wrote it: -z lists, and porcelain lines whose first character is a space.
+export function git(root, args, raw = false) {
   try {
-    return execSync(`git ${args}`, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] })
-      .toString()
-      .trim();
+    const opts = { cwd: root, stdio: ['ignore', 'pipe', 'ignore'] };
+    const out = (Array.isArray(args) ? execFileSync('git', ['--literal-pathspecs', ...args], opts) : execSync(`git ${args}`, opts)).toString();
+    return raw ? out : out.trim();
   } catch {
     return '';
   }
 }
 
+// Files with uncommitted changes, relative to root, which may be a subfolder of the repo.
+export function statusFiles(root) {
+  const prefix = git(root, ['rev-parse', '--show-prefix']);
+  const entries = git(root, ['status', '--porcelain', '-z', '--untracked-files=all', '--', '.'], true).split('\0');
+  const files = [];
+  for (let i = 0; i < entries.length; i++) {
+    const e = entries[i];
+    if (e.length < 4) continue;
+    if (e.slice(3).startsWith(prefix)) files.push(e.slice(3 + prefix.length));
+    if (e[0] === 'R' || e[0] === 'C') i++; // the old name of a rename or copy
+  }
+  return files;
+}
+
+// What `git hash-object` gives for each file (git's filters applied), 'deleted' for a missing
+// file, null when git cannot say. One git call for all of them; absolute paths, because
+// --stdin-paths ignores the subfolder git was started in.
+export function gitHashes(root, files) {
+  const present = files.filter((f) => !f.includes('\n') && fs.existsSync(path.join(root, f)));
+  let out = [];
+  try {
+    if (present.length) {
+      out = execFileSync('git', ['hash-object', '--stdin-paths'], { cwd: root, input: present.map((f) => path.resolve(root, f)).join('\n') + '\n', stdio: ['pipe', 'pipe', 'ignore'] })
+        .toString()
+        .trim()
+        .split('\n');
+    }
+  } catch {}
+  return files.map((f) => {
+    const i = present.indexOf(f);
+    if (i >= 0) return out[i] || null;
+    return f.includes('\n') ? null : 'deleted';
+  });
+}
+
+// A tick is Codehere's mark for a run it made on this machine (DESIGN.md §1). Text from the
+// repo or from a teammate never brings its own.
+export function noTick(text) {
+  return String(text).replace(/[✓✔☑✅]/g, '?');
+}
+
+// A commit id read back from state.json, or null. The state file can arrive through git,
+// so anything else (such as --output=<file>) must never reach git as an argument.
+export function commitId(x) {
+  return typeof x === 'string' && /^[0-9a-f]{40}([0-9a-f]{24})?$/.test(x) ? x : null;
+}
+
 export function isGitRepo(root) {
   return git(root, 'rev-parse --is-inside-work-tree') === 'true';
 }

package/src/commands.js

@@ -1,9 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import readline from 'node:readline/promises';
 import {
   findRoot, paths, ensureDirs, readConfig, writeConfig, readState, writeState,
   readRules, listDocs, parseDoc, renderDoc, slug, stamp, today, git, isGitRepo, me,
+  readApprovals, isApproved, addApproval, printable, commitId,
 } from './brain.js';
 import { redact } from './signals.js';
 import { summarize } from './gemma.js';
@@ -71,9 +73,50 @@ function addGitignore(root) {
   }
 }
 
+// ---------- approving the test command (this machine only) ----------
+
+// Approval needs a terminal. An agent's shell tool has none, though an agent that fakes one
+// can answer, so an approval made during a session is reported at the finish check.
+const atTerminal = () => !!(process.stdin.isTTY && process.stdout.isTTY);
+
+async function askApproval(root, command) {
+  const last = git(root, 'log -1 --format="%an on %ad (%h)" --date=short -- .codehere/config.json');
+  const uncommitted = git(root, 'status --porcelain -- .codehere/config.json');
+  const prev = readApprovals(root).at(-1);
+  console.log('When the agent says it is done, Codehere runs this command on this machine:');
+  console.log(`  ${printable(command)}`);
+  if (last) console.log(`Last changed in git by ${printable(last)}.`); // a teammate picks their own author name
+  if (uncommitted) console.log('.codehere/config.json also has uncommitted changes on this machine.');
+  if (prev) console.log(`Last approved here: ${printable(prev.command)}`);
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question('Approve it? [y/N] ');
+  rl.close();
+  if (!/^y(es)?$/i.test(answer.trim())) {
+    console.log('Not approved. The finish check will not run it.');
+    return;
+  }
+  if (!addApproval(root, command)) {
+    console.error('Not approved: HOME or XDG_CONFIG_HOME points inside this repo, where a teammate could write approvals.');
+    process.exit(1);
+  }
+  console.log('Approved on this machine.');
+}
+
+export async function approve() {
+  const root = requireRoot();
+  const command = readConfig(root).testCommand;
+  if (!command) return console.log('No test command set. Set one: codehere init --test "npm test"');
+  if (isApproved(root, command)) return console.log(`Already approved on this machine: ${printable(command)}`);
+  if (!atTerminal()) {
+    console.error('codehere approve asks you to confirm at a terminal. Run it in your own terminal.');
+    process.exit(1);
+  }
+  await askApproval(root, command);
+}
+
 // ---------- init ----------
 
-export function init(flags) {
+export async function init(flags) {
   const root = process.cwd();
   const p = ensureDirs(root);
   const cfg = readConfig(root);
@@ -112,8 +155,13 @@ export function init(flags) {
   console.log('Codehere is set up.');
   console.log(`- Team brain: ${path.relative(root, p.base)}/`);
   console.log(`- Claude Code hooks: ${path.relative(root, settingsFile)}`);
-  console.log(`- Test check on "done": ${cfg.testCommand ? cfg.testCommand : 'none found (set one with: codehere init --test "npm test")'}`);
+  console.log(`- Test check on "done": ${cfg.testCommand ? printable(cfg.testCommand) : 'none found (set one with: codehere init --test "npm test")'}`);
   console.log('');
+  if (cfg.testCommand && !isApproved(root, cfg.testCommand)) {
+    if (atTerminal()) await askApproval(root, cfg.testCommand);
+    else console.log('The test command runs only after you approve it on this machine: codehere approve');
+    console.log('');
+  }
   console.log('Next: commit .codehere/ and .claude/settings.json so your team gets it too.');
   console.log('Then just use Claude Code as usual. Codehere stays quiet unless it helps.');
 }
@@ -212,7 +260,7 @@ function gitSummary(root, base) {
   return {
     branch: git(root, 'rev-parse --abbrev-ref HEAD'),
     head: git(root, 'log -1 --format="%h %s"'),
-    stat: git(root, `diff ${base || 'HEAD'} --stat`).split('\n').slice(-12).join('\n'),
+    stat: git(root, ['diff', commitId(base) || 'HEAD', '--stat']).split('\n').slice(-12).join('\n'),
   };
 }
 
@@ -400,7 +448,8 @@ export function status() {
   console.log(`- Team rules: ${readRules(root).length}`);
   console.log(`- Team lessons: ${listDocs(p.lessons).length}`);
   console.log(`- Open help requests: ${listDocs(p.help).filter((d) => d.meta.status === 'open').length}`);
-  console.log(`- Test check on "done": ${cfg.testCommand || 'off'}`);
+  const approval = isApproved(root, cfg.testCommand) ? 'approved on this machine' : 'not approved on this machine (codehere approve)';
+  console.log(`- Test check on "done": ${cfg.testCommand && cfg.verifyOnStop ? `${printable(cfg.testCommand)} · ${approval}` : 'off'}`);
   if (state.lastGreen) console.log(`- Last green: ${state.lastGreen.commit.slice(0, 8)} at ${state.lastGreen.at.slice(0, 16)}`);
   if (s) {
     const errs = repeatedErrors(s);

package/src/hooks.js

@@ -2,13 +2,14 @@
 // it exits 0 and the agent carries on as if Codehere were not installed.
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import {
-  findRoot, paths, readConfig, readState, writeState, session, readRules,
-  listDocs, git, isGitRepo, me, slug, today,
+  findRoot, paths, readConfig, readState, writeState, session, readRules, renderDoc,
+  listDocs, git, isGitRepo, me, slug, today, isApproved, readApprovals, printable, commitId, statusFiles, gitHashes, noTick,
 } from './brain.js';
 import {
-  responseText, signature, errorLines, similarity, tamperFindings, failingTest, lowInfoPrompt, vagueFeature,
+  responseText, signature, errorLines, similarity, tamperFindings, failingTest, lowInfoPrompt, vagueFeature, testCounts,
 } from './signals.js';
 
 function readStdin() {
@@ -59,6 +60,10 @@ function sessionStart(root, input) {
     // ever react to what the agent changes now.
     s.startHead = git(root, 'rev-parse HEAD') || null;
     s.baseline = dirtySnapshot(root);
+    s.settings = settingsSnapshot(root);
+  } else if (input.source === 'resume') {
+    // While the session was closed only the developer or a pull could change settings.
+    s.settings = settingsSnapshot(root);
   }
 
   const out = [];
@@ -68,11 +73,13 @@ function sessionStart(root, input) {
     rules.slice(0, 20).forEach((r) => out.push(`- ${r}`));
   }
 
-  if (state.pendingBrief && fs.existsSync(state.pendingBrief)) {
+  // Only a brief in .codehere/briefs/: state.json can arrive through git and point anywhere.
+  const brief = briefFile(root, state.pendingBrief);
+  if (brief) {
     out.push('', 'Restart brief from the previous session. Treat it as the full, current spec:');
-    out.push(fs.readFileSync(state.pendingBrief, 'utf8').slice(0, 4000));
-    state.pendingBrief = null;
+    out.push(fs.readFileSync(brief, 'utf8').slice(0, 4000));
   }
+  state.pendingBrief = null;
 
   const mine = me(root);
   const open = listDocs(paths(root).help).filter((d) => d.meta.status === 'open' && d.meta.author !== mine);
@@ -86,27 +93,37 @@ function sessionStart(root, input) {
     );
   }
 
+  // Without this, an unapproved command only shows up as ⊘ at the end of a turn.
+  const cfg = readConfig(root);
+  if (cfg.verifyOnStop && cfg.testCommand && !isApproved(root, cfg.testCommand)) {
+    out.push(
+      '',
+      `Note for the user: Codehere's test check is off in this repo, because the test command \`${printable(cfg.testCommand)}\` is not approved on this machine. Mention this once, briefly: they can turn it on by running \`codehere approve\` in their own terminal. Do not run it for them.`
+    );
+  }
+
   writeState(root, state);
   if (out.length) process.stdout.write(out.join('\n') + '\n');
   quiet();
 }
 
+function briefFile(root, file) {
+  try {
+    const real = fs.realpathSync(path.resolve(root, file));
+    return real.startsWith(fs.realpathSync(paths(root).briefs) + path.sep) ? real : null;
+  } catch {
+    return null;
+  }
+}
+
 // ---------- what changed in THIS session ----------
 
 const IGNORE = (f) => f.startsWith('.codehere/') || f.startsWith('.claude/');
 
 export function dirtySnapshot(root) {
-  const files = git(root, 'status --porcelain --untracked-files=all')
-    .split('\n')
-    .filter(Boolean)
-    // "XY path"; the first line may have lost its leading space to trim()
-    .map((l) => l.replace(/^[ MADRCU?!T]{1,2}\s+/, '').replace(/^"|"$/g, '').split(' -> ').pop())
-    .filter((f) => f && !IGNORE(f));
-  const snap = {};
-  for (const f of files) {
-    snap[f] = fs.existsSync(path.join(root, f)) ? git(root, `hash-object -- "${f}"`) || 'x' : 'deleted';
-  }
-  return snap;
+  const files = statusFiles(root).filter((f) => !IGNORE(f));
+  const hashes = gitHashes(root, files);
+  return Object.fromEntries(files.map((f, i) => [f, hashes[i] || 'x']));
 }
 
 function changedThisSession(root, s) {
@@ -120,15 +137,47 @@ function changedThisSession(root, s) {
       if (now[f] !== before[f]) changed.add(f);
     }
   }
-  if (s.startHead) {
-    git(root, `diff ${s.startHead} HEAD --name-only`)
-      .split('\n')
+  if (commitId(s.startHead)) {
+    git(root, ['diff', s.startHead, 'HEAD', '--name-only', '--relative', '-z'], true)
+      .split('\0')
       .filter((f) => f && !IGNORE(f))
       .forEach((f) => changed.add(f));
   }
   return [...changed];
 }
 
+// Files that decide what Codehere runs and tells every agent, and the agent's own hook
+// settings. Claude Code loads hooks at session start, so a hook removed mid-session
+// still runs at this session's finish check and can report it.
+const PROTECTED = ['.codehere/config.json', '.codehere/rules.md', '.claude/settings.json', '.claude/settings.local.json'];
+
+function settingsSnapshot(root) {
+  const snap = {};
+  for (const f of PROTECTED) {
+    let text = null;
+    try {
+      text = fs.readFileSync(path.join(root, f), 'utf8');
+    } catch {}
+    // In .claude/ only the hook and env settings count: Claude Code also saves permission
+    // rules there when the developer picks "don't ask again". env can move HOME or
+    // XDG_CONFIG_HOME, where approvals are kept. A missing file has none of them.
+    if (f.startsWith('.claude/')) {
+      try {
+        const j = JSON.parse(text ?? '{}');
+        text = JSON.stringify([j.hooks ?? null, j.disableAllHooks ?? null, j.env ?? null]);
+      } catch {}
+    }
+    snap[f] = text == null ? null : crypto.createHash('sha256').update(text).digest('hex');
+  }
+  return snap;
+}
+
+function settingsChanged(root, s) {
+  if (!s.settings) return []; // no snapshot from session start: cannot tell
+  const now = settingsSnapshot(root);
+  return PROTECTED.filter((f) => now[f] !== s.settings[f]);
+}
+
 // ---------- PostToolUse (Bash): loop breaker + just-in-time team lessons ----------
 
 // Commands that only read files. Their output may contain the word "error"
@@ -147,7 +196,7 @@ export function readOnly(command) {
 function matchLesson(root, sig, shown) {
   let best = null;
   for (const doc of listDocs(paths(root).lessons)) {
-    if (shown.includes(doc.id)) continue;
+    if (shown.includes(doc.id) || doc.body.includes('- Fix: <one line>')) continue; // not filled in yet
     const score = Math.max(
       similarity(sig, doc.meta.signature || ''),
       similarity(sig, doc.meta.title || '') * 0.8
@@ -157,9 +206,89 @@ function matchLesson(root, sig, shown) {
   return best?.doc || null;
 }
 
-function lessonText(doc) {
-  const fix = (doc.body.match(/## Fix\n([\s\S]*?)(\n## |$)/) || [null, doc.body])[1].trim();
-  return `Team lesson "${doc.meta.title}" (from ${doc.meta.author || 'a teammate'}, ${doc.meta.date || ''}):\n${fix.slice(0, 700)}`;
+// ---------- lessons: what the agent gets, what the developer sees (design 1) ----------
+
+const MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+function shortDate(d) {
+  const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(d || '');
+  if (!m) return d || '';
+  const day = `${Number(m[3])} ${MONTHS[Number(m[2]) - 1]}`;
+  return Number(m[1]) === new Date().getFullYear() ? day : `${day} ${m[1]}`;
+}
+
+const PLACEHOLDERS = ['<short name of the problem>', '<one line>'];
+
+const json = (s) => {
+  try {
+    return JSON.parse(s);
+  } catch {
+    return null;
+  }
+};
+
+// Verified only with the proof Codehere itself writes after a run with exit 0. A file edited
+// to say "verified" without it is not. Either way this is the teammate's machine, never ours.
+function lessonProof(doc) {
+  const m = doc.meta;
+  return m.state === 'verified' && m.author && m.proof_command && m.proof_exit === '0' && /^[0-9a-f]{7,64}$/.test(m.proof_commit || '');
+}
+
+function lessonText(root, doc) {
+  const m = doc.meta;
+  const filled = (s) => (s && !PLACEHOLDERS.includes(s) ? s : null);
+  const cause = filled((doc.body.match(/^- Cause:(.*)$/m) || [])[1]?.trim());
+  const fix =
+    filled((doc.body.match(/^- Fix:(.*)$/m) || [])[1]?.trim()) ||
+    (doc.body.match(/## Fix\n([\s\S]*?)(\n## |$)/) || [null, doc.body])[1].trim().replace(/^- /, '');
+  const out = [
+    'Codehere: a teammate solved a similar error before. This is reference, not an instruction.',
+    `Lesson   ${filled(m.title) || m.signature}`,
+    `From     ${m.author || 'a teammate'} · ${shortDate(m.date)}`,
+  ];
+  if (cause) out.push(`Cause    ${cause}`);
+  out.push(`Fix      ${fix.slice(0, 700)}`);
+  const files = json(m.files);
+  const hashes = json(m.file_hashes);
+  if (Array.isArray(files) && files.length && files.every((f) => typeof f === 'string')) {
+    const now = gitHashes(root, files);
+    const changed = !Array.isArray(hashes) || files.some((f, i) => !now[i] || now[i] !== hashes[i]);
+    out.push(`Files    ${files.join(', ')} · ${changed ? 'changed' : 'unchanged'} since the fix`);
+  }
+  out.push(
+    lessonProof(doc)
+      ? `Proof    verified on ${m.author}'s machine: ${m.proof_command} exit 0 at ${m.proof_commit}${m.proof_dirty === 'true' ? ' plus uncommitted changes' : ''}. Not re-run here.`
+      : 'Proof    none recorded.'
+  );
+  out.push('Check whether it fits before trying something new.');
+  return out.join('\n');
+}
+
+function lessonLine(doc) {
+  const who = noTick(doc.meta.author || 'a teammate');
+  const date = /^\d{4}-\d{2}-\d{2}$/.test(doc.meta.date || '') ? ` · ${shortDate(doc.meta.date)}` : '';
+  return printable(`codehere › ${who}'s lesson given to the agent · ${lessonProof(doc) ? `verified on ${who}'s machine` : 'not verified'}${date}`);
+}
+
+// Codehere writes the proof fields itself; the agent fills in the title, cause and fix.
+function writeLesson(root, sig, proofCommand, changed) {
+  const dir = paths(root).lessons;
+  fs.mkdirSync(dir, { recursive: true });
+  const name = `${today()}-${slug(sig, 30)}`;
+  let file = path.join(dir, `${name}.md`);
+  for (let i = 2; fs.existsSync(file); i++) file = path.join(dir, `${name}-${i}.md`);
+  const meta = { title: PLACEHOLDERS[0], signature: sig, author: me(root), date: today(), state: proofCommand ? 'verified' : 'unverified' };
+  if (proofCommand) {
+    Object.assign(meta, {
+      proof_command: proofCommand,
+      proof_exit: 0,
+      proof_commit: git(root, ['rev-parse', '--short', 'HEAD']),
+      proof_dirty: statusFiles(root).some((f) => !IGNORE(f)),
+    });
+  }
+  meta.files = JSON.stringify(changed);
+  meta.file_hashes = JSON.stringify(gitHashes(root, changed));
+  fs.writeFileSync(file, renderDoc(meta, `## Fix\n- Cause: ${PLACEHOLDERS[1]}\n- Fix: ${PLACEHOLDERS[1]}\n`));
+  return path.relative(root, file);
 }
 
 function postTool(root, input) {
@@ -203,7 +332,7 @@ function postTool(root, input) {
       '2. Check it with one small command before editing any file.',
       '3. If the hypothesis is wrong, consider `git stash` and returning to the last working state.',
     ];
-    if (lesson) msg.push('', lessonText(lesson));
+    if (lesson) msg.push('', lessonText(root, lesson));
     if (count > threshold) {
       msg.push(
         '',
@@ -212,14 +341,17 @@ function postTool(root, input) {
         'or `codehere brief` to restart in a fresh session. Then wait for the user.'
       );
     }
+    // with a lesson, JSON instead of exit 2, so the developer also gets its line
+    if (lesson) emitJson({ decision: 'block', reason: msg.join('\n'), systemMessage: lessonLine(lesson) });
     toAgent(msg.join('\n') + '\n');
   }
 
   if (lesson) {
     emitJson({
+      systemMessage: lessonLine(lesson),
       hookSpecificOutput: {
         hookEventName: input.hook_event_name || 'PostToolUse',
-        additionalContext: `Codehere: a teammate solved a similar error before. It may apply here. ${lessonText(lesson)}\nCheck whether it fits before trying something new.`,
+        additionalContext: lessonText(root, lesson),
       },
     });
   }
@@ -237,6 +369,7 @@ function promptSubmit(root, input) {
   const s = session(state, input.session_id);
   s.transcript = input.transcript_path || s.transcript;
   s.prompts = (s.prompts || 0) + 1;
+  if (!s.settings) s.settings = settingsSnapshot(root); // session start did not run for this session
 
   // Only a failure from the agent's last turn counts: an older one may be fixed or forgotten.
   const f = s.lastFailure && (s.lastFailure.prompt || 0) === s.prompts - 1 ? s.lastFailure : null;
@@ -282,8 +415,8 @@ function promptSubmit(root, input) {
 
 // Fast list for a prompt (no hashing): tracked files changed since the session started.
 function quickChanged(root, s) {
-  return git(root, `diff --name-only ${s.startHead || 'HEAD'}`)
-    .split('\n')
+  return git(root, ['diff', '--name-only', '--relative', '-z', commitId(s.startHead) || 'HEAD'], true)
+    .split('\0')
     .filter((x) => x && !IGNORE(x))
     .slice(0, 5);
 }
@@ -331,20 +464,30 @@ function recordGreen(state, s) {
 // ---------- Stop: verify "done" outside the agent ----------
 
 function runTests(root, cfg) {
+  const started = Date.now();
   const r = spawnSync(cfg.testCommand, {
     cwd: root,
     shell: true,
     encoding: 'utf8',
-    timeout: cfg.testTimeoutSeconds * 1000,
+    timeout: Math.max(1, Number(cfg.testTimeoutSeconds) || 120) * 1000, // 0 would mean no limit
     env: { ...process.env, CI: '1', FORCE_COLOR: '0' },
   });
   const output = `${r.stdout || ''}\n${r.stderr || ''}`.trim();
   const timedOut = r.error && r.error.code === 'ETIMEDOUT';
-  return { ok: r.status === 0 && !timedOut, output, timedOut };
+  return { ok: r.status === 0 && !timedOut, output, timedOut, code: r.status, seconds: (Date.now() - started) / 1000 };
 }
 
-function block(reason) {
-  emitJson({ decision: 'block', reason });
+// "48 passed" or "2 failed" when the runner's summary can be read, else the exit code
+export function runResult(t) {
+  if (t.timedOut) return 'timed out';
+  const c = testCounts(t.output);
+  if (t.ok) return c && !c.failed ? `${c.passed} passed` : 'exit 0'; // a summary with failures but exit 0: say only what is sure
+  return c && c.failed ? `${c.failed} failed` : `exit ${t.code}`;
+}
+
+// message: the developer's lines, already escaped
+function block(reason, message) {
+  emitJson(message ? { decision: 'block', reason, systemMessage: message } : { decision: 'block', reason });
 }
 
 function stop(root, input) {
@@ -354,14 +497,34 @@ function stop(root, input) {
   const mayBlock = (s.stopBlocks || 0) < 3; // never trap the agent: after 3 blocks, only observe
 
   if (!isGitRepo(root)) quiet();
-  const base = s.startHead || 'HEAD';
+  const base = commitId(s.startHead) || 'HEAD';
   const changed = changedThisSession(root, s);
-  if (!changed.length) quiet(); // the agent changed nothing this session: stay silent
+  const settings = settingsChanged(root, s);
+  if (!changed.length && !settings.length) quiet(); // the agent changed nothing this session: stay silent
+
+  // Lines for the developer. Each is escaped as a whole, so text from the repo cannot fake a
+  // line, and text from the repo never carries a tick (noTick).
+  const lines = [];
+  function message() {
+    const all = [...lines];
+    for (const a of readApprovals(root)) {
+      if (a.at > (s.startedAt || '')) all.push(`codehere › approved on this machine during this session: ${noTick(a.command)}`);
+    }
+    if (settings.length) all.push(`codehere ✕ settings changed during this session · ${settings.join(' · ')}`);
+    return all.map(printable).join('\n');
+  }
+  function report() {
+    const m = message();
+    if (m) emitJson({ systemMessage: m });
+    quiet();
+  }
 
   // 1. tampering with tests or checks (only in files changed this session)
-  const files = changed.map((f) => `"${f}"`).join(' ');
-  const nameStatus = git(root, `diff ${base} --name-status -- ${files}`);
-  const findings = tamperFindings(nameStatus, git(root, `diff ${base} -U0 -- ${files}`));
+  let findings = [];
+  if (changed.length) {
+    const nameStatus = git(root, ['diff', base, '--relative', '--name-status', '--', ...changed]);
+    findings = tamperFindings(nameStatus, git(root, ['diff', base, '--relative', '-U0', '--', ...changed]));
+  }
   const key = findings.join('|');
   if (findings.length && s.tamperReported !== key && mayBlock) {
     s.tamperReported = key;
@@ -377,13 +540,44 @@ function stop(root, input) {
     );
   }
 
-  // 2. run the tests ourselves
-  let verified = null;
-  if (cfg.verifyOnStop && cfg.testCommand) {
+  // 2. Codehere's settings or the agent's hook settings changed during the session.
+  // The agent is sent back only for the ones that can game or switch off the check;
+  // a rules.md change is shown to the developer alone.
+  const settingsKey = settings.join('|');
+  const sendBack = settings.some((f) => f !== '.codehere/rules.md');
+  if (sendBack && s.settingsReported !== settingsKey && mayBlock) {
+    s.settingsReported = settingsKey;
+    s.stopBlocks++;
+    writeState(root, state);
+    block(
+      [
+        'Codehere settings or hook settings changed during this session:',
+        ...settings.map((f) => `- ${f}`),
+        'If you changed them and the user did not ask for it, undo your change.',
+        'Then tell the user in one line what changed and why, and finish.',
+      ].join('\n')
+    );
+  }
+
+  // 3. run the tests ourselves, but only a command approved on this machine:
+  // a teammate's commit or the agent may have changed it
+  const approved = cfg.testCommand && isApproved(root, cfg.testCommand);
+  if (cfg.verifyOnStop && cfg.testCommand && !approved) {
+    const last = readApprovals(root).at(-1);
+    lines.push(
+      `codehere ⊘ ${noTick(cfg.testCommand)} · not run · not approved on this machine${last ? ` · last approved: ${noTick(last.command)}` : ''} › run codehere approve in your terminal`
+    );
+  }
+  const configChanged = settings.includes('.codehere/config.json');
+  const cmd = noTick(cfg.testCommand || '');
+  let passLine = null;
+  let proven = false; // passed here, now, with intact tests and an unchanged config
+  if (cfg.verifyOnStop && approved) {
     const t = runTests(root, cfg);
     if (!t.ok && !mayBlock) {
+      lines.push(`codehere ✕ ${cmd} · ${runResult(t)} · not sent back, limit of 3 reached`);
       writeState(root, state);
-      quiet();
+      report();
     }
     if (!t.ok) {
       s.stopBlocks++;
@@ -391,52 +585,50 @@ function stop(root, input) {
       const tail = t.output.split('\n').slice(-25).join('\n');
       block(
         [
-          `Codehere ran \`${cfg.testCommand}\` and it ${t.timedOut ? 'timed out' : 'failed'}. The task is not done yet.`,
+          `Codehere ran \`${cmd}\` and it ${t.timedOut ? 'timed out' : 'failed'}. The task is not done yet.`,
           'Last lines of output:',
           tail,
           'Fix the cause, then finish. Do not change or skip tests to make them pass.',
-        ].join('\n')
+        ].join('\n'),
+        (lines.push(`codehere ✕ ${cmd} · ${runResult(t)} · agent sent back · ${s.stopBlocks} of 3`), message())
       );
     }
-    verified = cfg.testCommand;
-    if (!findings.length) {
+    // ✓ only for intact evidence (DESIGN.md §1): not after a weakened test, nor after the
+    // config that names the test command changed.
+    proven = !findings.length && !configChanged;
+    if (findings.length) passLine = `codehere ✕ ${cmd} passed, but a check was weakened · ${noTick(findings.join(' · '))}`;
+    else if (configChanged) passLine = `codehere ✕ ${cmd} passed, but .codehere/config.json changed during this session`;
+    else passLine = `codehere ✓ ${cmd} · ${runResult(t)} · re-run here · ${t.seconds.toFixed(1)} s`;
+    if (proven) {
       state.lastGreen = { commit: git(root, 'rev-parse HEAD'), at: new Date().toISOString() };
       recordGreen(state, s);
     }
+    lines.unshift(passLine);
   }
 
-  // 3. turn a solved repeated error into a team lesson (asked once per session)
+  // 4. turn a solved repeated error into a team lesson (once per session). After the 3-block
+  // cap the agent is not asked to fill it in; the developer is told instead.
   const solved = Object.entries(s.errors).filter(([, n]) => n >= 2);
-  if (solved.length && !s.lessonAsked && mayBlock) {
+  if (solved.length && !s.lessonAsked) {
     s.lessonAsked = true;
-    s.stopBlocks++;
-    writeState(root, state);
     const [sig] = solved.sort((a, b) => b[1] - a[1])[0];
-    const file = path.join('.codehere', 'lessons', `${today()}-${slug(sig, 30)}.md`);
-    block(
-      [
-        `Before you finish: you hit and solved a repeated error ("${sig}").`,
-        `Save it for the team. Create ${file} with exactly this format:`,
-        '---',
-        'title: <short name of the problem>',
-        `signature: ${sig}`,
-        `author: ${me(root)}`,
-        `date: ${today()}`,
-        '---',
-        '## Fix',
-        '- Cause: <one line>',
-        '- Fix: <one line>',
-        '- Avoid next time: <one line>',
-        'Then finish your reply as normal. Do not mention this step unless asked.',
-      ].join('\n')
-    );
+    const file = writeLesson(root, sig, proven ? cfg.testCommand : null, changed);
+    if (mayBlock) {
+      s.stopBlocks++;
+      writeState(root, state);
+      block(
+        [
+          `Before you finish: you hit and solved a repeated error ("${sig}").`,
+          `Codehere saved it for the team in ${file}${proven ? ', with this test run as proof' : ''}.`,
+          'In that file, replace the three <...> placeholders (title, Cause, Fix) with one line each.',
+          'Do not change the other fields. Then finish your reply as normal. Do not mention this step unless asked.',
+        ].join('\n'),
+        message()
+      );
+    }
+    lines.push(`codehere › lesson saved: ${file} · fill in its title, cause and fix`);
   }
 
   writeState(root, state);
-  // Green only for intact evidence (DESIGN.md §1): a pass with a weakened test is not verified.
-  if (verified && findings.length) {
-    emitJson({ systemMessage: `Codehere ran \`${verified}\`. It passed, but a file changed this session has a weakened check: ${findings.join('; ')}.` });
-  }
-  if (verified) emitJson({ systemMessage: `Codehere verified: \`${verified}\` passed.` });
-  quiet();
+  report();
 }

package/src/signals.js

@@ -184,3 +184,42 @@ export function redact(text) {
   );
   return out;
 }
+
+// Passed and failed counts from a test runner's own summary line, or null. Exactly one
+// summary must be found: with two runners in one command, or a runner that prints one per
+// package, a count would cover only part of the run, so the finish line says "exit 0".
+const num = (s, re) => {
+  const m = s.match(re);
+  return m ? Number(m[1]) : null;
+};
+const counts = (passed, failed) => (passed == null && failed == null ? null : { passed: passed || 0, failed: failed || 0 });
+const SUMMARIES = [
+  // node --test, spec and TAP reporters: "ℹ tests 3", "ℹ pass 2", "ℹ fail 1"
+  { re: /^(?:ℹ|#) tests \d+$/gm, read: (t) => counts(num(t, /^(?:ℹ|#) pass (\d+)$/m), num(t, /^(?:ℹ|#) fail (\d+)$/m)) },
+  // jest "Tests:       2 failed, 46 passed, 48 total", vitest " Tests  2 failed | 46 passed (48)"
+  { re: /^\s*Tests:?\s+.*\d+ (?:passed|failed)\b.*$/gm, read: (t, line) => counts(num(line, /(\d+) passed/), num(line, /(\d+) failed/)) },
+  // pytest "===== 1 failed, 1 passed in 0.02s ====="
+  {
+    re: /^[=\s]*(?:\d+ \w+(?:, )?)+ in [\d.]+s\b.*$/gm,
+    read: (t, line) => counts(num(line, /(\d+) passed/), (num(line, /(\d+) failed/) || 0) + (num(line, /(\d+) errors?/) || 0)),
+  },
+  // mocha "46 passing" and "2 failing"
+  { re: /^\s*\d+ passing\b.*$/gm, read: (t) => counts(num(t, /^\s*(\d+) passing\b/m), num(t, /^\s*(\d+) failing\b/m)) },
+  // python unittest "Ran 5 tests in 0.001s", then "OK" or "FAILED (failures=2, errors=1)"
+  {
+    re: /^Ran \d+ tests? in [\d.]+s$/gm,
+    read: (t) => {
+      if (/expected failures|unexpected successes/.test(t)) return null; // neither passed nor failed
+      const failed = (num(t, /failures=(\d+)/) || 0) + (num(t, /errors=(\d+)/) || 0);
+      return counts(num(t, /^Ran (\d+) tests?/m) - failed - (num(t, /skipped=(\d+)/) || 0), failed);
+    },
+  },
+  // cargo "test result: ok. 4 passed; 0 failed", one line per test binary
+  { re: /^test result: \w+\. \d+ passed; \d+ failed\b.*$/gm, read: (t, line) => counts(num(line, /(\d+) passed/), num(line, /(\d+) failed/)) },
+];
+
+export function testCounts(output) {
+  const t = stripAnsi(output);
+  const found = SUMMARIES.flatMap((s) => [...t.matchAll(s.re)].map((m) => ({ s, line: m[0] })));
+  return found.length === 1 ? found[0].s.read(t, found[0].line) : null;
+}