codehere 2.0.0-beta.0 → 2.0.0-beta.2

package/README.md

@@ -2,7 +2,7 @@
 
 **A team brain for vibe coders.** It stops your AI coding agent from going in circles, checks "done" for real, and shares what your team learns. It works through plain files in git.
 
-Codehere is built to remove work, not add it. You keep using Claude Code as usual. Codehere talks to the agent, not to you, and stays silent unless it helps.
+Codehere is built to remove work, not add it. You keep using Claude Code or Codex CLI as usual. Codehere talks to the agent, not to you, and stays silent unless it helps.
 
 ## What it does
 
@@ -23,12 +23,20 @@ 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
-git add .codehere .claude/settings.json .gitignore
+codehere init --agent claude,codex   # finds your test command, adds the hooks, asks you to approve the command
+git add .codehere .claude/settings.json .codex/hooks.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.
+Use `--agent claude` or `--agent codex` for one agent; with no `--agent`, `init` sets up Claude Code. The hooks go in `.claude/settings.json` and `.codex/hooks.json`.
+
+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.
+
+Codex runs a repo's hooks only after each developer trusts them. Open Codex in the repo, trust the project if asked, then type `/hooks` and trust the four Codehere hooks. Do it once per clone, and again after an update that changes the hooks. Until then Codex skips them, and `codex exec` does not warn.
+
+`codehere uninstall` removes the hooks, and `.codehere/` too when it holds no rules, lessons, help cards or briefs.
+
+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,14 +53,44 @@ 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.
 
+## Which agents
+
+| | Claude Code | Codex CLI |
+|---|---|---|
+| Team rules at session start | yes | yes |
+| A teammate's lesson after a failed command | yes | yes |
+| "Same error 3 times: stop and find the root cause" | yes | yes, given next to the error output |
+| Context added to a short prompt such as "still broken" | yes | yes |
+| Finish check: your tests re-run, the agent sent back | yes | yes |
+| Your one line (✓ ✕ ⊘ ›) | yes | in the interactive screen, as `↳ Hook · codehere ✓ …`; not in `codex exec` |
+| Restart-brief suggestion in long sessions | yes | no |
+| Before it works | nothing | each developer trusts the hooks in `/hooks` |
+| MCP tools, instruction file | no | no |
+| Tested on | 2.1.311 with haiku: [result](docs/conformance/2026-10-27-claude-2.1.311-haiku.md) | 0.164.0 with a local model (Qwen 3.5 9B through Ollama): [result](docs/conformance/2026-10-27-codex-0.164.0-qwen3.5-9b-q4-K-M.md) |
+
+The rows for rules, lessons and the finish check are checked on the real agent by `node scripts/conformance.mjs`. The other rows are checked by `npm test` on hook inputs recorded from each agent.
+
 ## Commands
 
 ```
-codehere init [--test "npm test"]       set up (safe to run again)
+codehere init [--agent claude,codex] [--test "npm test"]
+                                        set up (safe to run again)
+codehere approve                        let the finish check run the test command on this machine
+codehere uninstall                      remove Codehere from this repo (asks first)
 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 +111,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.
@@ -97,12 +135,18 @@ node demo/demo.mjs --step   # press Enter between scenes (good for a live talk)
 npm test                    # end-to-end checks
 ```
 
-## Known limits (2.0.0, not released yet)
+## Known limits (2.0 beta)
 
-- 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".
+- Claude Code and Codex CLI. Copilot and OpenCode are next. See [Which agents](#which-agents) for what works on each.
+- 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`.
+- In `codex exec`, Codex shows you none of Codehere's lines. The agent still gets every message, and the finish check still sends it back.
+- `codehere approve` and `codehere uninstall` ask only in your own terminal. They refuse when Claude Code or Codex is among the processes above them, and inside Codex's sandbox. An agent that detaches its terminal on purpose can still answer, so the finish check of a session that was open tells you when an approval or an uninstall happened.
+- 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`; Codex asks each developer to trust a new or changed hook first. Both are your repo's code, with the same trust as running it yourself.
+- When the agent changes `.codehere/config.json`, `.codehere/rules.md`, the hook and env settings in `.claude/settings*.json`, or `.codex/hooks.json` or `.codex/config.toml` 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

@@ -8,7 +8,9 @@ const flags = {};
 const pos = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
-  if (a.startsWith('--')) {
+  if (a.startsWith('--') && a.indexOf('=') > 2) {
+    flags[a.slice(2, a.indexOf('='))] = a.slice(a.indexOf('=') + 1);
+  } else if (a.startsWith('--')) {
     const key = a.slice(2);
     const next = argv[i + 1];
     if (!BOOLEAN.has(key) && next !== undefined && !next.startsWith('--')) {
@@ -23,7 +25,10 @@ const [command, ...rest] = pos;
 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 init [--agent claude,codex] [--test "npm test"]
+                                      set up .codehere/ and the agents' hooks (default: Claude Code)
+  codehere approve                    let the finish check run the test command on this machine
+  codehere uninstall                  remove Codehere's hooks, and .codehere/ if it holds no team content
 
 Team brain
   codehere rule ["text"]              add a team rule (or list rules)
@@ -42,16 +47,20 @@ When you're stuck
   codehere status                     what Codehere has seen
   codehere stats                      turns to green, loops stopped, session size
 
-Hooks (called by Claude Code, not by you)
-  codehere hook session-start | prompt | post-tool | stop
+Hooks (called by the agent, not by you)
+  codehere hook session-start | prompt | post-tool | stop [--agent codex]
 `;
 
 const run = async () => {
   switch (command) {
     case 'hook':
-      return runHook(rest[0]);
+      return runHook(rest[0], flags.agent);
     case 'init':
       return cmd.init(flags);
+    case 'approve':
+      return cmd.approve();
+    case 'uninstall':
+      return cmd.uninstall();
     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.2",
   "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,172 @@ 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;
+}
+
+export function removeApprovals(root) {
+  const file = approvalsFile(root);
+  const all = readAllApprovals(root);
+  if (!file || !(repoKey(root) in all.repos)) return;
+  delete all.repos[repoKey(root)];
+  fs.writeFileSync(file, JSON.stringify(all, null, 2) + '\n');
+}
+
+// uninstall leaves a note here, outside the repo. A session that was open when it ran still has
+// its hooks loaded, but its state and maybe .codehere/ are gone: its finish check reads the note.
+export function markRemoved(root, removed = true) {
+  const file = approvalsFile(root);
+  const all = readAllApprovals(root);
+  const notes = all.removed && typeof all.removed === 'object' ? all.removed : {};
+  if (!file || (!removed && !(repoKey(root) in notes))) return;
+  if (removed) notes[repoKey(root)] = new Date().toISOString();
+  else delete notes[repoKey(root)];
+  all.removed = notes;
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, JSON.stringify(all, null, 2) + '\n');
+}
+
+// When uninstall ran for dir or a folder above it, else null.
+export function removedAt(dir) {
+  for (let d = path.resolve(dir); ; d = path.dirname(d)) {
+    const at = readAllApprovals(d).removed?.[repoKey(d)];
+    if (typeof at === 'string') return at;
+    if (path.dirname(d) === d) return null;
+  }
+}
+
+// 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,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import readline from 'node:readline/promises';
+import { execFileSync } from 'node:child_process';
 import {
   findRoot, paths, ensureDirs, readConfig, writeConfig, readState, writeState,
   readRules, listDocs, parseDoc, renderDoc, slug, stamp, today, git, isGitRepo, me,
+  readApprovals, isApproved, addApproval, removeApprovals, markRemoved, printable, commitId,
 } from './brain.js';
 import { redact } from './signals.js';
 import { summarize } from './gemma.js';
@@ -17,6 +20,21 @@ const HOOK_EVENTS = {
   Stop: { cmd: 'codehere hook stop', timeout: 180 },
 };
 
+// Keep these strings stable: Codex asks every developer to trust a hook again when its definition changes.
+const CODEX_HOOK_EVENTS = {
+  SessionStart: { cmd: 'codehere hook session-start --agent codex' },
+  UserPromptSubmit: { cmd: 'codehere hook prompt --agent codex', timeout: 10 },
+  PostToolUse: { cmd: 'codehere hook post-tool --agent codex', matcher: 'Bash' },
+  Stop: { cmd: 'codehere hook stop --agent codex', timeout: 180 },
+};
+
+const AGENTS = {
+  claude: { name: 'Claude Code', file: '.claude/settings.json', events: HOOK_EVENTS },
+  codex: { name: 'Codex CLI', file: '.codex/hooks.json', events: CODEX_HOOK_EVENTS },
+};
+
+const ours = (h) => typeof h?.command === 'string' && h.command.startsWith('codehere hook ');
+
 function requireRoot() {
   const root = findRoot();
   if (!root) {
@@ -39,18 +57,18 @@ function detectTestCommand(root) {
   return null;
 }
 
-function mergeClaudeSettings(root) {
-  const dir = path.join(root, '.claude');
-  const file = path.join(dir, 'settings.json');
-  fs.mkdirSync(dir, { recursive: true });
+// Claude Code's .claude/settings.json and Codex's .codex/hooks.json share this shape.
+function mergeHooks(root, agent) {
+  const file = path.join(root, agent.file);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
   let settings = {};
   try {
     settings = JSON.parse(fs.readFileSync(file, 'utf8'));
   } catch {}
   settings.hooks = settings.hooks || {};
-  for (const [event, spec] of Object.entries(HOOK_EVENTS)) {
+  for (const [event, spec] of Object.entries(agent.events)) {
     const list = (settings.hooks[event] = settings.hooks[event] || []);
-    const already = list.some((g) => (g.hooks || []).some((h) => h.command === spec.cmd));
+    const already = list.some((g) => (g?.hooks || []).some((h) => h?.command === spec.cmd));
     if (already) continue;
     const hook = { type: 'command', command: spec.cmd };
     if (spec.timeout) hook.timeout = spec.timeout;
@@ -59,7 +77,55 @@ function mergeClaudeSettings(root) {
     list.push(group);
   }
   fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
-  return file;
+}
+
+// Takes Codehere's hooks out of the agent's settings file, keeping everything else.
+// A file left with nothing in it is removed, and its folder if that is then empty.
+function removeHooks(root, agent) {
+  const file = path.join(root, agent.file);
+  let settings;
+  try {
+    settings = JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return false;
+  }
+  const hooks = settings.hooks && typeof settings.hooks === 'object' ? settings.hooks : {};
+  let found = false;
+  for (const event of Object.keys(hooks)) {
+    if (!Array.isArray(hooks[event])) continue;
+    hooks[event] = hooks[event]
+      .filter((g) => g && typeof g === 'object')
+      .map((g) => {
+        const all = Array.isArray(g.hooks) ? g.hooks : [];
+        const kept = all.filter((h) => !ours(h));
+        if (kept.length !== all.length) found = true;
+        return { ...g, hooks: kept };
+      })
+      .filter((g) => g.hooks.length);
+    if (!hooks[event].length) delete hooks[event];
+  }
+  if (!found) return false;
+  if (!Object.keys(hooks).length) delete settings.hooks;
+  if (Object.keys(settings).length) {
+    fs.writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  } else {
+    fs.rmSync(file);
+    try {
+      fs.rmdirSync(path.dirname(file));
+    } catch {} // not empty: something else lives there
+  }
+  return true;
+}
+
+function installedAgents(root) {
+  return Object.values(AGENTS).filter((a) => {
+    try {
+      const hooks = JSON.parse(fs.readFileSync(path.join(root, a.file), 'utf8')).hooks || {};
+      return Object.values(hooks).some((gs) => Array.isArray(gs) && gs.some((g) => Array.isArray(g?.hooks) && g.hooks.some(ours)));
+    } catch {
+      return false;
+    }
+  });
 }
 
 function addGitignore(root) {
@@ -71,9 +137,90 @@ function addGitignore(root) {
   }
 }
 
+// ---------- approving the test command (this machine only) ----------
+
+// Approving and uninstalling need the developer's own terminal: a terminal on stdin and stdout,
+// and no agent among the processes above this one. An agent's commands run under its process,
+// even in a terminal it opens (Codex can). Inside Codex's sandbox ps is not allowed, so the
+// parents cannot be read, which counts as under an agent. An agent that detaches its terminal
+// on purpose can still answer, so the finish check reports an approval or an uninstall.
+const AGENT_PROCESSES = new Set(['claude', 'codex', 'copilot', 'opencode']);
+const PS = fs.existsSync('/bin/ps') ? '/bin/ps' : '/usr/bin/ps';
+function underAgent() {
+  let pid = process.ppid;
+  for (let i = 0; i < 100 && pid > 1; i++) {
+    let line;
+    try {
+      line = execFileSync(PS, ['-o', 'ppid=,comm=', '-p', String(pid)], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    } catch {
+      return true;
+    }
+    const m = /^(\d+)\s+(.+)$/.exec(line);
+    if (!m || AGENT_PROCESSES.has(path.basename(m[2]).toLowerCase())) return true;
+    pid = Number(m[1]);
+  }
+  return pid > 1;
+}
+const atTerminal = () => !!(process.stdin.isTTY && process.stdout.isTTY) && !underAgent();
+
+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 in your own terminal, not through an agent. Run it there.');
+    process.exit(1);
+  }
+  await askApproval(root, command);
+}
+
 // ---------- init ----------
 
-export function init(flags) {
+const RULES_MD = '# Team rules\n\nOne rule per line, starting with "- ". Written by people, not by the agent.\nEvery agent session on this repo loads these.\n\n';
+const README_MD = [
+  '# .codehere — this team\'s brain',
+  '',
+  'Plain markdown, shared through git. Commit and push it like code.',
+  '',
+  '- `rules.md`: team rules every agent session loads',
+  '- `lessons/`: errors someone already solved; shown to the agent only when the same error appears',
+  '- `help/`: help cards; teammates see them with `codehere inbox`',
+  '- `briefs/`: restart briefs for fresh sessions',
+  '- `local/`: this machine only (git-ignored)',
+  '',
+].join('\n');
+
+export async function init(flags) {
+  const names = flags.agent === undefined ? ['claude'] : String(flags.agent === true ? '' : flags.agent).split(',').map((x) => x.trim().toLowerCase());
+  if (!names.every((n) => Object.hasOwn(AGENTS, n))) {
+    console.error(`Unknown agent "${printable(flags.agent === true ? '' : flags.agent)}". Use --agent claude, --agent codex or --agent claude,codex.`);
+    process.exit(1);
+  }
+  const agents = [...new Set(names)].map((n) => AGENTS[n]);
   const root = process.cwd();
   const p = ensureDirs(root);
   const cfg = readConfig(root);
@@ -81,41 +228,103 @@ export function init(flags) {
   else if (!cfg.testCommand) cfg.testCommand = detectTestCommand(root);
   writeConfig(root, cfg);
 
-  if (!fs.existsSync(p.rules)) {
-    fs.writeFileSync(
-      p.rules,
-      '# Team rules\n\nOne rule per line, starting with "- ". Written by people, not by the agent.\nEvery agent session on this repo loads these.\n\n'
-    );
-  }
-  fs.writeFileSync(
-    path.join(p.base, 'README.md'),
-    [
-      '# .codehere — this team\'s brain',
-      '',
-      'Plain markdown, shared through git. Commit and push it like code.',
-      '',
-      '- `rules.md`: team rules every agent session loads',
-      '- `lessons/`: errors someone already solved; shown to the agent only when the same error appears',
-      '- `help/`: help cards; teammates see them with `codehere inbox`',
-      '- `briefs/`: restart briefs for fresh sessions',
-      '- `local/`: this machine only (git-ignored)',
-      '',
-    ].join('\n')
-  );
+  if (!fs.existsSync(p.rules)) fs.writeFileSync(p.rules, RULES_MD);
+  fs.writeFileSync(path.join(p.base, 'README.md'), README_MD);
   for (const d of [p.lessons, p.help, p.briefs]) {
     const keep = path.join(d, '.gitkeep');
     if (!fs.existsSync(keep)) fs.writeFileSync(keep, '');
   }
   addGitignore(root);
-  const settingsFile = mergeClaudeSettings(root);
+  for (const a of agents) mergeHooks(root, a);
+  markRemoved(root, false);
 
   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")'}`);
+  for (const a of agents) console.log(`- ${a.name} hooks: ${a.file}`);
+  console.log(`- Test check on "done": ${cfg.testCommand ? printable(cfg.testCommand) : 'none found (set one with: codehere init --test "npm test")'}`);
   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.');
+  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('');
+  }
+  if (agents.includes(AGENTS.codex)) {
+    console.log("Codex runs a repo's hooks only after each developer trusts them. Open Codex here, trust the project if asked,");
+    console.log('then type /hooks and trust the four Codehere hooks. Until then Codex skips them, and `codex exec` does not warn.');
+    console.log('');
+  }
+  console.log(`Next: commit .codehere/ and ${agents.map((a) => a.file).join(' and ')} so your team gets it too.`);
+  console.log(`Then just use ${agents.map((a) => a.name).join(' or ')} as usual. Codehere stays quiet unless it helps.`);
+}
+
+// ---------- uninstall ----------
+
+function removeGitignoreLine(root) {
+  const file = path.join(root, '.gitignore');
+  if (!fs.existsSync(file)) return;
+  const lines = fs.readFileSync(file, 'utf8').split('\n');
+  const kept = lines.filter((l) => l !== '.codehere/local/');
+  if (kept.length === lines.length) return;
+  if (kept.join('\n').trim()) fs.writeFileSync(file, kept.join('\n'));
+  else fs.rmSync(file);
+}
+
+function filesIn(dir) {
+  return fs.readdirSync(dir, { withFileTypes: true }).flatMap((e) => {
+    const f = path.join(dir, e.name);
+    return e.isDirectory() ? filesIn(f) : [f];
+  });
+}
+
+const count = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+
+// Like approve, it needs the developer's own terminal, so the agent cannot switch Codehere off.
+// .codehere/ goes only when it holds nothing but what init wrote.
+export async function uninstall() {
+  const root = findRoot();
+  if (!root) {
+    console.error('No .codehere folder here. Nothing to remove.');
+    process.exit(1);
+  }
+  // findRoot walks up: from a folder with no .codehere/ it can reach the home folder
+  const home = fs.realpathSync(root) === fs.realpathSync(os.homedir());
+  if (home || !isGitRepo(root)) {
+    console.error(`The nearest .codehere/ is in ${printable(root)}, ${home ? 'your home folder' : 'which is not a git repo'}. Nothing removed.`);
+    process.exit(1);
+  }
+  if (!atTerminal()) {
+    console.error('codehere uninstall asks you to confirm in your own terminal, not through an agent. Run it there.');
+    process.exit(1);
+  }
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await rl.question(`Remove Codehere from ${printable(root)}? [y/N] `);
+  rl.close();
+  if (!/^y(es)?$/i.test(answer.trim())) return console.log('Nothing removed.');
+
+  for (const a of Object.values(AGENTS)) {
+    if (removeHooks(root, a)) console.log(`- Removed Codehere's hooks from ${a.file}`);
+  }
+  removeApprovals(root);
+  markRemoved(root);
+  const p = paths(root);
+  fs.rmSync(p.local, { recursive: true, force: true });
+  const readme = path.join(p.base, 'README.md');
+  const written = [p.config, p.rules, readme, ...[p.lessons, p.help, p.briefs].map((d) => path.join(d, '.gitkeep'))];
+  const rules = readRules(root).length;
+  const docs = [p.lessons, p.help, p.briefs].map((d) => listDocs(d).length);
+  const other = filesIn(p.base).filter((f) => !written.includes(f)).length - docs.reduce((a, b) => a + b, 0);
+  const edited = [[p.rules, RULES_MD], [readme, README_MD]].filter(([f, text]) => fs.existsSync(f) && fs.readFileSync(f, 'utf8') !== text).map(([f]) => path.basename(f));
+  const held = [[rules, 'rule'], [docs[0], 'lesson'], [docs[1], 'help card'], [docs[2], 'brief'], [other, 'other file']].filter(([n]) => n).map(([n, w]) => count(n, w));
+  if (!rules) held.push(...edited.map((f) => `an edited ${f}`));
+  else if (edited.includes('README.md')) held.push('an edited README.md');
+  if (!held.length) {
+    fs.rmSync(p.base, { recursive: true, force: true });
+    removeGitignoreLine(root); // kept otherwise: a session still open would write local/ again
+    console.log('- Removed .codehere/');
+  } else {
+    console.log(`- Kept .codehere/: it holds ${held.join(', ')}. Delete it yourself if the team no longer needs it.`);
+  }
+  console.log('Codehere is removed from this repo on this machine. Commit the changes so your team gets them too.');
 }
 
 // ---------- rules ----------
@@ -212,7 +421,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'),
   };
 }
 
@@ -397,10 +606,12 @@ export function status() {
   const { state, s } = lastSession(root);
   const p = paths(root);
   console.log('Codehere status');
+  console.log(`- Agents: ${installedAgents(root).map((a) => a.name).join(', ') || 'none (codehere init --agent claude,codex)'}`);
   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

@@ -1,14 +1,16 @@
-// Claude Code hook handlers. Every handler fails open: if anything goes wrong,
-// it exits 0 and the agent carries on as if Codehere were not installed.
+// Hook handlers for Claude Code and Codex CLI (--agent codex). Every handler fails open: if
+// anything goes wrong, 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,
+  removedAt,
 } 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() {
@@ -33,14 +35,20 @@ function toAgent(message) {
 
 const quiet = () => process.exit(0);
 
-export async function runHook(event) {
+export async function runHook(event, agent) {
   const input = readStdin();
-  const root = findRoot(input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd());
-  if (!root) quiet();
+  const start = input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+  const root = findRoot(start);
+  if (!root) {
+    // uninstall ran while this session was open: its hooks still run, .codehere/ is gone
+    const at = event === 'stop' && removedAt(start);
+    if (at) emitJson({ systemMessage: removedLine(at) });
+    quiet();
+  }
   try {
     if (event === 'session-start') return sessionStart(root, input);
     if (event === 'prompt') return promptSubmit(root, input);
-    if (event === 'post-tool') return postTool(root, input);
+    if (event === 'post-tool') return postTool(root, input, agent === 'codex' ? 'codex' : 'claude');
     if (event === 'stop') return stop(root, input);
   } catch (err) {
     if (process.env.CODEHERE_DEBUG) console.error(err);
@@ -59,6 +67,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 +80,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 +100,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/');
+const IGNORE = (f) => f.startsWith('.codehere/') || f.startsWith('.claude/') || f.startsWith('.codex/');
 
 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 +144,49 @@ 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 agents' own hook
+// settings. Claude Code and Codex load 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', '.codex/hooks.json', '.codex/config.toml'];
+
+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.
+    // Codex keeps what it saves in the user's own config, so .codex/ files count whole.
+    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);
+  // a session that started before a file was protected has no hash for it
+  return PROTECTED.filter((f) => f in s.settings && 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 +205,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,12 +215,92 @@ 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]}`;
 }
 
-function postTool(root, input) {
+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, agent) {
   if (input.tool_name && input.tool_name !== 'Bash') quiet();
   const command = (input.tool_input && input.tool_input.command) || '';
   if (readOnly(command)) quiet();
@@ -203,7 +341,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 +350,25 @@ function postTool(root, input) {
         'or `codehere brief` to restart in a fresh session. Then wait for the user.'
       );
     }
+    // Codex replaces the command's output with a block's text (or exit 2's), so the agent
+    // would lose the error. There it goes in as context next to the output.
+    if (agent === 'codex') {
+      emitJson({
+        ...(lesson ? { systemMessage: lessonLine(lesson) } : {}),
+        hookSpecificOutput: { hookEventName: 'PostToolUse', additionalContext: msg.join('\n') },
+      });
+    }
+    // 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 +386,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 +432,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 +481,32 @@ 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}`;
+}
+
+const removedLine = (at) => `codehere ✕ codehere uninstall ran at ${new Date(at).toTimeString().slice(0, 5)} · this repo's checks are removed`;
+
+// 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 +516,36 @@ 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);
+  const removed = removedAt(root);
+  if (!changed.length && !settings.length && !removed) 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(' · ')}`);
+    if (removed) all.push(removedLine(removed));
+    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 +561,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 +606,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;
+}