nearly-cli 0.1.5 → 0.1.7

package/README.md

@@ -22,7 +22,7 @@ Watch the first thirty seconds. The cover says what the diff cannot: an action t
 
 ## What it needs
 
-Node 18 or newer, Claude Code signed in, and git. No dependencies and no API key: agents run on your existing Claude subscription.
+Node 18 or newer, git, and one of the seven coding agents below signed in. No dependencies and no API key of its own: agents run on whatever subscription you already have.
 
 ### Platforms
 
@@ -46,6 +46,73 @@ but a whole session with a real agent, and a real push through the hook, have
 only been done on macOS. If you are the first to try either on Windows or Linux,
 an issue with what broke would be genuinely useful.
 
+### Agents
+
+The editor is not the question. Claude Code in VS Code, in a JetBrains IDE, in a
+plain terminal or over SSH all read the same `.claude/settings.local.json`, so
+all four are already covered. Neither is the model — the gate sits between the
+agent and your machine, below whichever model is answering.
+
+The harness making the tool calls is the question, because that is what exposes
+the hook. Seven are supported:
+
+| | Config it writes | Holds for a human | Record |
+|---|---|---|---|
+| Claude Code | `.claude/settings.local.json` | yes | full |
+| Cursor | `.cursor/hooks.json` | yes | full |
+| Antigravity | `.agents/hooks.json` | yes | full |
+| GitHub Copilot CLI | `.github/hooks/nearly.json` | yes | full |
+| Gemini CLI | `.gemini/settings.json` | yes | full |
+| Codex CLI | `.codex/hooks.json` | yes | no prompts, one turn |
+| Windsurf | `.windsurf/hooks.json` | until Cascade gives up | shell and file tools only |
+
+`nearly` turns on whichever of these the repo shows signs of, and Claude Code
+either way. `nearly --agent=cursor` forces one, `--agent=all` forces all of them,
+and `nearly agents` prints what is actually wired here.
+
+**One of these rows is not like the others.** Claude Code has been run end to end
+against a live agent. The other six are built from each vendor's published hook
+documentation and tested against payloads copied from it — every adapter has to
+refuse `rm -rf` and have that refusal land in words its harness acts on, or the
+suite fails. That is a good bet. It is not the same as having watched it work,
+and `nearly agents` says so in as many words:
+
+```
+  Run against a live agent: Claude Code
+  Built to the vendor's published hook spec and tested against payloads
+  copied from it, but never yet run against the real thing:
+    Cursor, Antigravity, GitHub Copilot CLI, Codex CLI, Gemini CLI, Windsurf
+```
+
+If you use one of those six, the most useful thing you can do is try it and open
+an issue saying what broke.
+
+#### What the adapters actually do
+
+The server speaks one dialect. Everything downstream of a hook — the consent
+gradient, the recording, the record page, the PR comment — reads Claude Code's
+shape and nothing else. An adapter is a translation at the edge, about thirty
+lines: their payload in, ours out; our answer in, theirs out.
+
+Two decisions make that small enough to trust. Nearly never asks the harness to
+ask — every one of them can prompt, and we want none of it, because their dialog
+is not the record. We hold the hook open and answer once a human has. And tools
+are matched by shape as well as by name: `run_command`, `shell`,
+`run_terminal_cmd` and `bash` are all Bash, and anything carrying a command
+string is treated as Bash even if nobody here has heard of it — because if it
+isn't, the never-rules don't apply to it and `rm -rf` walks through a gate that
+reports itself as working. Anything still unrecognised falls to `ask`.
+
+The harness's own name for the tool travels with the call, so the record says
+`run_command` where Antigravity said `run_command`, while the rule you set
+applies to every one of them.
+
+#### Not supported
+
+Zed's built-in agent, Aider, Kilo Code, Warp and the hosted builders (Replit,
+Lovable, Bolt, v0) expose no blocking pre-tool hook. There is nothing to attach
+to, and no adapter can change that.
+
 ## Use it on your own repo
 
 One command, in the repo you want recorded.
@@ -63,7 +130,8 @@ npx nearly-cli
 ```
 ✓ Nearly is on for my-app
 
-  · every Claude Code session here is gated and recorded
+  · Claude Code sessions here are gated and recorded (run end to end against a live agent)
+  · Cursor sessions here are gated and recorded (built to their published hook spec, not yet run against a live agent)
   · upgrades reach this repo automatically
   · the record is offered when you push
 
@@ -142,7 +210,18 @@ Every tool call passes through an HTTP `PreToolUse` hook to this server, which s
 
 "Allow always" and "Never" turn a decision into a rule for the rest of the run, keyed by tool and first word of the command, or file extension for edits. In lab mode every turn is committed in the agent's worktree by the `Stop` hook, so **Undo turn** is a `git reset --hard HEAD~1`.
 
-Agents in lab mode are real Claude Code sessions (`claude -p`) on your Claude subscription, each in its own git worktree under `workspace/.worktrees/`. No API key, no paid infrastructure, anywhere in this project.
+Lab mode is off by default. `nearly open` shows your own sessions and what
+needs you — the gate, which is what you installed this for. `nearly lab` adds
+the panel for starting agents from the dashboard, which is a different job and
+no longer the first thing a new user is asked about.
+
+Agents in lab mode are real Claude Code sessions (`claude -p`) on your Claude
+subscription, each on its own branch in its own git worktree. You pick which
+repo to branch from — the dashboard offers the ones you have turned Nearly on
+for — and the branch starts from that repo's HEAD, so it begins where you
+actually are rather than on some assumed `main`. Worktrees live under
+`~/.nearly/workspace/.worktrees/`, outside the installed package, so upgrading
+never deletes one. No API key, no paid infrastructure, anywhere in this project.
 
 ## What the record actually contains
 
@@ -248,12 +327,16 @@ Claude Code treats a hook that times out, errors, or returns anything other than
 npm test
 ```
 
-41 tests, no dependencies, about 30 seconds. They run on a fresh clone with no
+83 tests, no dependencies, about 50 seconds. They run on a fresh clone with no
 agent, no network and no Claude subscription, because the fixtures are the two
 recorded sessions committed in `recordings/demo`.
 
 What they hold the project to:
 
+- **Every adapter.** That `rm -rf` is refused in all seven harnesses' dialects,
+  that the refusal comes back in words each one acts on, that a session appears
+  from whichever field that harness calls its session id, and that a payload none
+  of them would ever send leaves the agent working rather than hanging.
 - **The consent gradient.** That destructive commands are denied without asking,
   that a never pattern still fires when the command is buried in a chain, that an
   unclassified tool is held rather than allowed, and that "always" for `git status`
@@ -278,17 +361,18 @@ The claim this project makes is testable: a reviewer who sees the session record
 ## Roadmap
 
 - **Read Prempti's audit trail as an input.** Their recording is structured, local, Apache-licensed and covers more than ours. The recap builder reads its own JSONL today; a second reader would let anyone already running Prempti get a session record without changing their gate.
-- **A Cursor adapter.** The server speaks JSON in and JSON out, so a tool that runs a script instead of calling a URL needs about twenty lines of translation. Cursor's `beforeShellExecution` is the first target.
+- **Run the six unverified adapters against their real agents.** They are built to spec and tested against the vendors' own documented payloads, but documentation is not a build. Each one that gets run for real either becomes a verified row or becomes a bug report.
 - **Port the recap player to React.** It is one self-contained page today.
 
 ## Files
 
+- `server/adapters.mjs`, the seven harnesses and the translation at each edge
 - `server/index.mjs`, spawn sessions, hooks, policy, recorder, undo
 - `ui/index.html`, sessions, triage of pending approvals, rules, log
 - `scripts/attach.mjs`, install or remove the hooks in a repo of your own; `scripts/post-recap.mjs`, comment the recap on its PR
 - `scripts/build-recap.mjs` + `ui/recap.template.html`, narrated recap page per session
 - `scripts/publish-pages.mjs`, build the `docs/` folder GitHub Pages serves
 - `scripts/install-push-hook.mjs` + `scripts/push-record.mjs`, hand the branch record over at `git push`
-- `workspace/`, the repo agents work on (seeded with the Tempo demo)
+- `~/.nearly/`, where recordings, records, settings and agent worktrees are kept — outside the package, so an upgrade cannot destroy them
 - `recordings/<session>.jsonl`, every event and decision; `recordings/demo/` is committed so the records can be rebuilt from source
 - `STUDY.md`, the protocol for testing whether any of this helps a reviewer

package/bin/nearly.mjs

@@ -4,8 +4,10 @@
 //   nearly              turn it on for the repo you are in
 //   nearly off          turn it off again
 //   nearly open         open the dashboard
+//   nearly lab          open it with the panel for starting agents
 //   nearly record       build the record for the current branch
 //   nearly post         put that record on the pull request
+//   nearly agents       which agents this repo is gated for
 //   nearly voices       list the narration voices you have
 //   nearly server       run the server in the foreground (it self-starts otherwise)
 //   nearly hook <ev>    internal: what the Claude Code hooks call
@@ -34,7 +36,12 @@ const run = async (file, args = []) => {
   process.exit(r.status ?? 0);
 };
 
-const [cmd = 'attach', ...rest] = process.argv.slice(2);
+// A leading flag is not a command. `nearly --agent=cursor` and `nearly --off`
+// are how the docs say to do those things, and both used to land on "Unknown
+// command" because the first argument was read as a subcommand name.
+const argv = process.argv.slice(2);
+const leadingFlag = argv[0]?.startsWith('-') && !['--help', '-h', '--which'].includes(argv[0]);
+const [cmd = 'attach', ...rest] = leadingFlag ? ['attach', ...argv] : argv;
 
 async function main() {
 switch (cmd) {
@@ -68,6 +75,9 @@ switch (cmd) {
   case 'publish':
     return run(s('publish-pages.mjs'), rest);
 
+  case 'agents':
+    return run(s('agents.mjs'), rest);
+
   case 'voices':
     return run(s('build-recap.mjs'), ['--voices']);
 
@@ -77,8 +87,10 @@ switch (cmd) {
     return run(join(root, 'server', 'index.mjs'), rest);
   }
 
-  case 'open': {
-    const url = 'http://127.0.0.1:47653';
+  case 'lab': case 'open': {
+    // `open` is the gate: your sessions and what needs you. `lab` adds the
+    // panel for starting agents from here, which is a different job.
+    const url = 'http://127.0.0.1:47653' + (cmd === 'lab' ? '/?lab=1' : '');
     spawn(process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open',
       [url], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' }).unref();
     console.log(url);
@@ -90,8 +102,10 @@ switch (cmd) {
   nearly              turn it on for the repo you are in
   nearly off          turn it off again
   nearly open         open the dashboard
+  nearly lab          open it with the panel for starting agents
   nearly record       build the record for the current branch
   nearly post         put that record on the pull request
+  nearly agents       which agents this repo is gated for
   nearly voices       list the narration voices you have
   nearly server       run the server in the foreground
 `);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.5",
+  "version": "0.1.7",
   "description": "A pull request tells you what changed. Nearly tells you what nearly happened: the commands a human refused, the pushes policy blocked, the turns rolled back.",
   "type": "module",
   "bin": {
@@ -34,6 +34,6 @@
   },
   "homepage": "https://anujpatel06.github.io/nearly/",
   "scripts": {
-    "test": "node --test --test-concurrency=1 test/policy.test.mjs test/server.test.mjs test/record.test.mjs test/resilience.test.mjs"
+    "test": "node --test --test-concurrency=1 test/policy.test.mjs test/server.test.mjs test/record.test.mjs test/resilience.test.mjs test/detect.test.mjs test/adapters.test.mjs test/spawn.test.mjs"
   }
 }

package/scripts/agents.mjs

@@ -0,0 +1,61 @@
+// What Nearly can gate, and how much of that is a claim rather than a
+// demonstration.
+//
+//   nearly agents        what this repo is gated for, and what else is possible
+//
+// Printed because the difference matters. An adapter written from a vendor's
+// hook documentation is a reasonable bet; it is not the same thing as having
+// watched an agent be stopped. Saying so is cheap, and the alternative — a tool
+// that reports coverage it has not earned — is the exact failure this project
+// was built to catch.
+
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { ADAPTERS } from '../server/adapters.mjs';
+import { detect, installed } from './detect.mjs';
+
+const dim = (s) => `\x1b[2m${s}\x1b[0m`;
+const bold = (s) => `\x1b[1m${s}\x1b[0m`;
+const ok = (s) => `\x1b[32m${s}\x1b[0m`;
+
+const repo = resolve(process.argv.slice(2).find((a) => !a.startsWith('--')) || process.cwd());
+const here = new Set(detect(repo).map((d) => d.id));
+const machine = new Set(installed().map((d) => d.id));
+
+// The config file existing proves nothing: Cursor writes .cursor/hooks.json for
+// its own reasons. What proves the gate is wired is our command being inside it.
+// Anything weaker would let this command report coverage it has not got.
+const gated = (a) => {
+  const f = join(repo, a.config);
+  if (!existsSync(f)) return false;
+  try { return /nearly/i.test(readFileSync(f, 'utf8')); } catch { return false; }
+};
+
+const width = Math.max(...ADAPTERS.map((a) => a.name.length));
+const pad = (s) => s + ' '.repeat(width - s.length);
+
+console.log('');
+console.log(`  ${bold('Agents')} ${dim(repo)}`);
+console.log('');
+for (const a of ADAPTERS) {
+  const on = gated(a);
+  const mark = on ? ok('●') : dim('○');
+  const state = on ? 'gated here' : here.has(a.id) ? 'used here, not gated' : machine.has(a.id) ? 'installed, unused here' : 'not in use here';
+  console.log(`  ${mark} ${bold(pad(a.name))}  ${pad2(state)} ${dim(a.config)}`);
+}
+function pad2(s) { return s + ' '.repeat(Math.max(0, 22 - s.length)); }
+
+console.log('');
+const proven = ADAPTERS.filter((a) => a.verified);
+const claimed = ADAPTERS.filter((a) => !a.verified);
+console.log(`  ${ok('Run against a live agent:')} ${proven.map((a) => a.name).join(', ')}`);
+console.log(`  ${dim('Built to the vendor\'s published hook spec and tested against payloads')}`);
+console.log(`  ${dim('copied from it, but never yet run against the real thing:')}`);
+console.log(`  ${dim('  ' + claimed.map((a) => a.name).join(', '))}`);
+console.log('');
+console.log(dim('  If you use one of those, the useful thing you can do is try it and say'));
+console.log(dim('  what broke: github.com/anujpatel06/nearly/issues'));
+console.log('');
+console.log(dim('  nearly --agent=cursor    turn one on for this repo'));
+console.log(dim('  nearly --agent=all       turn on every one of them'));
+console.log('');

package/scripts/attach.mjs

@@ -6,8 +6,10 @@
 //
 // One command, once per repo. It installs everything and works out the rest:
 //
-//   · Claude Code hooks, so every session in this repo is gated and recorded
-//     whether you start it in a terminal, in VS Code, or in JetBrains
+//   · hooks for every coding agent this repo is driven by, so sessions are
+//     gated and recorded whether you start them in a terminal, in VS Code or in
+//     JetBrains. Claude Code always; Cursor, Antigravity, Copilot, Codex, Gemini
+//     and Windsurf when the repo shows signs of them, or on --agent=
 //   · a git pre-push hook, so the record is offered when the work leaves your
 //     machine
 //   · where the records are published, read from the Nearly's own remote
@@ -20,7 +22,9 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync, realpathSync } from
 import { join, resolve, dirname, basename } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { execFileSync, spawnSync } from 'node:child_process';
-import { dataRoot } from '../server/paths.mjs';
+import { dataRoot, paths } from '../server/paths.mjs';
+import { choose, installed as agentsOnMachine } from './detect.mjs';
+import { ADAPTERS } from '../server/adapters.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const HOOK = join(root, 'scripts', 'hook.mjs');
@@ -125,43 +129,53 @@ if (!existsSync(join(repo, '.git'))) {
 if (!off && installGlobally()) installed = onPath();
 
 // ---------------------------------------------------------------------------
-// Claude Code hooks
+// Agent hooks
 // ---------------------------------------------------------------------------
-const dir = join(repo, '.claude');
-const file = join(dir, 'settings.local.json');
-mkdirSync(dir, { recursive: true });
-
-let settings = {};
-if (existsSync(file)) {
-  try { settings = JSON.parse(readFileSync(file, 'utf8')); }
-  catch (e) { console.error(`Could not read ${file}: ${e.message}`); process.exit(1); }
+// Turning off removes every adapter, not just the ones this repo still shows
+// signs of, so nothing is left behind pointing at a command that will not run.
+const { chosen, unknown } = off ? { chosen: ADAPTERS, unknown: [] } : choose(repo, argv);
+if (unknown.length) {
+  console.error(`Unknown agent: ${unknown.join(', ')}`);
+  console.error(`Known: ${ADAPTERS.map((a) => a.id).join(', ')}`);
+  process.exit(1);
 }
-settings.hooks = settings.hooks || {};
-
-// Recognise our own entries by the script they run, so this is safe to re-run
-// and leaves anyone else's hooks alone.
-const ours = (m) => (m?.hooks || []).some((h) =>
-  /nearly/.test(String(h.command || '')) || String(h.command || '').includes(HOOK) ||
-  String(h.url || '').includes(`:${PORT}/hooks/`));
-for (const ev of Object.keys(settings.hooks)) {
-  settings.hooks[ev] = (settings.hooks[ev] || []).filter((m) => !ours(m));
-  if (!settings.hooks[ev].length) delete settings.hooks[ev];
+
+const wired = [];
+const notes = [];
+for (const a of chosen) {
+  const cmdFor = (ev) => `${hookCmd(ev)} ${name}` + (a.id === 'claude-code' ? '' : ` --adapter=${a.id}`);
+  try {
+    const r = off ? a.uninstall({ repo }) : a.install({ repo, cmdFor, name });
+    if (r?.error) { notes.push(`${a.name}: ${r.error}`); continue; }
+    if (off ? r?.removed : r?.file) wired.push({ ...a, file: r.file });
+    if (r?.note) notes.push(`${a.name}: ${r.note}`);
+  } catch (e) {
+    // One harness's config being unwritable must not cost you the others.
+    notes.push(`${a.name}: ${e.message}`);
+  }
 }
 
-if (!off) {
-  const entry = (ev, timeout) => ({
-    hooks: [{ type: 'command', command: `${hookCmd(ev)} ${name}`, timeout }],
-  });
-  const add = (event, ev, timeout) => { settings.hooks[event] = [...(settings.hooks[event] || []), entry(ev, timeout)]; };
-  add('SessionStart', 'session-start', 20);
-  add('UserPromptSubmit', 'prompt', 20);
-  add('PreToolUse', 'pre-tool', 600);   // long enough to hold while a human decides
-  add('PostToolUse', 'post-tool', 20);
-  add('Stop', 'stop', 30);
-  add('SessionEnd', 'session-end', 120);
+// Remember this repo, so the dashboard can offer it before anything has run in
+// it. A list of paths and nothing else: it is a convenience, and it is rebuilt
+// by simply turning Nearly on again.
+try {
+  const f = paths.repos();
+  // On a machine that has never run Nearly, ~/.nearly does not exist yet and
+  // this write fails with ENOENT. It used to fail into a bare catch, so the
+  // list was silently never created and the dashboard could never offer a repo
+  // — invisible on every machine except a genuinely fresh one.
+  mkdirSync(dirname(f), { recursive: true });
+  let list = [];
+  try { list = JSON.parse(readFileSync(f, 'utf8')); } catch { /* first one */ }
+  // Prune as we go: a repo that has been moved or deleted is noise in a list
+  // whose only job is to offer you somewhere to start.
+  list = list.filter((r) => r !== repo && existsSync(join(r, '.git')));
+  if (!off) list.unshift(repo);
+  writeFileSync(f, JSON.stringify(list.slice(0, 50), null, 2) + '\n');
+} catch (e) {
+  // Not fatal — the gate does not depend on it — but not silent either.
+  notes.push(`could not remember this repo for the dashboard: ${e.message}`);
 }
-if (!Object.keys(settings.hooks).length) delete settings.hooks;
-writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
 
 // ---------------------------------------------------------------------------
 // git pre-push hook
@@ -193,27 +207,35 @@ function pagesUrl() {
 // An address already configured wins: it was either set deliberately or worked
 // out here before, and it survives the project being renamed.
 function configured() {
-  try {
-    const f = join(root, '.nearly.json');
-    if (existsSync(f)) return JSON.parse(readFileSync(f, 'utf8')).urlBase || null;
-  } catch { /* fall through */ }
+  // The legacy path is read, never written: an upgrade destroys it, so the
+  // first run after this change is the last chance to carry it forward.
+  for (const f of [paths.config(), join(root, '.nearly.json')]) {
+    try {
+      if (existsSync(f)) {
+        const u = JSON.parse(readFileSync(f, 'utf8')).urlBase;
+        if (u) return u;
+      }
+    } catch { /* try the next one */ }
+  }
   return null;
 }
 const derived = pagesUrl();
 const base = process.env.NEARLY_URL_BASE || configured() || derived;
 if (base && !off) {
   try {
-    const cfg = join(root, '.nearly.json');
+    const cfg = paths.config();
     const prev = existsSync(cfg) ? JSON.parse(readFileSync(cfg, 'utf8')) : {};
     writeFileSync(cfg, JSON.stringify({ ...prev, urlBase: base }, null, 2) + '\n');
-  } catch { /* the env var still works */ }
+  } catch (e) { notes.push(`could not save where records publish: ${e.message}`); }
 }
 
 // ---------------------------------------------------------------------------
 console.log('');
 if (off) {
   console.log(`${bold('Nearly off')} for ${dim(repo)}`);
-  console.log('  Claude Code hooks removed');
+  console.log(wired.length
+    ? `  hooks removed: ${wired.map((a) => a.name).join(', ')}`
+    : '  no agent hooks of ours were installed');
   console.log(push.status === 0 ? '  pre-push hook removed' : dim('  pre-push hook was not ours, left alone'));
   console.log('');
   process.exit(0);
@@ -221,7 +243,10 @@ if (off) {
 
 console.log(`${ok('✓')} ${bold('Nearly is on')} for ${bold(name)}  ${dim(repo)}`);
 console.log('');
-console.log(`  ${ok('·')} every Claude Code session here is gated and recorded`);
+for (const a of wired) {
+  const how = a.verified ? dim(`(${a.verified})`) : dim('(built to their published hook spec, not yet run against a live agent)');
+  console.log(`  ${ok('·')} ${a.name} sessions here are gated and recorded ${how}`);
+}
 console.log(`  ${ok('·')} ${dim(updateNote())}`);
 console.log(`  ${ok('·')} ${push.status === 0 ? 'the record is offered when you push' : dim('pre-push hook skipped: ' + (push.stderr || '').trim().split('\n')[0])}`);
 if (base) {
@@ -233,6 +258,18 @@ if (base) {
   console.log(`    ${dim('to link them from a pull request, host that folder anywhere and:')}`);
   console.log(`    ${dim('NEARLY_URL_BASE=https://your-host/records nearly')}`);
 }
+for (const n of notes) console.log(`  ${dim('·')} ${dim(n)}`);
+
+// An agent you have on this machine but have not used here is worth a word, and
+// nothing more: having it installed is no reason to write files into this repo.
+const elsewhere = agentsOnMachine().filter((i) => !wired.some((w) => w.id === i.id));
+if (elsewhere.length) {
+  console.log('');
+  console.log(dim(`  Also installed here: ${elsewhere.map((e) => e.name).join(', ')}.`));
+  console.log(dim(`  Nothing in this repo suggests you use them for it, so they were left alone:`));
+  console.log(dim(`  nearly --agent=${elsewhere[0].id} turns one on.`));
+}
+
 console.log('');
 console.log(`  Now just work. Requests that need you appear at ${bold(`http://127.0.0.1:${PORT}`)}`);
 console.log(dim('  Nothing to leave running. Turn it off again with --off.'));

package/scripts/detect.mjs

@@ -0,0 +1,75 @@
+// Which coding agents is this repo actually driven by?
+//
+// The IDE is not the question. Claude Code inside VS Code or a JetBrains IDE is
+// still Claude Code, reading the same settings file, so those need nothing. What
+// matters is the harness making the tool calls, because that is what exposes the
+// hook Nearly attaches to.
+//
+// This exists so nobody has to know that. You run one command; it finds what you
+// use here and turns the gate on for each of them.
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { execFileSync } from 'node:child_process';
+import { ADAPTERS, byId } from '../server/adapters.mjs';
+
+// Signals beyond each adapter's own config file: the files a harness leaves in a
+// repo whether or not anybody has configured hooks in it.
+const MARKS = {
+  'claude-code': ['.claude', 'CLAUDE.md', '.claude/settings.json'],
+  cursor: ['.cursor', '.cursorrules', '.cursor/rules'],
+  antigravity: ['.agents', '.antigravity'],
+  copilot: ['.github/copilot-instructions.md', '.github/hooks'],
+  codex: ['.codex', 'AGENTS.md'],
+  gemini: ['.gemini'],
+  windsurf: ['.windsurf', '.windsurfrules'],
+};
+
+const CLIS = {
+  'claude-code': ['claude'], cursor: ['cursor-agent'], antigravity: ['agy'],
+  copilot: ['copilot'], codex: ['codex'], gemini: ['gemini'], windsurf: ['windsurf'],
+};
+
+function onPath(cmd) {
+  try {
+    execFileSync(process.platform === 'win32' ? 'where' : 'which', [cmd],
+      { stdio: ['ignore', 'ignore', 'ignore'] });
+    return true;
+  } catch { return false; }
+}
+
+// A config file in the repo is evidence about this repo. A CLI on PATH is only
+// evidence about the machine, so it is reported separately and never acted on:
+// having Gemini installed is not a reason to write files into someone's project.
+export function detect(repo) {
+  const found = [];
+  for (const a of ADAPTERS) {
+    const marks = [a.config, ...(MARKS[a.id] || [])];
+    const inRepo = marks.some((m) => existsSync(join(repo, m)));
+    if (inRepo) found.push({ id: a.id, name: a.name, why: 'configured in this repo' });
+  }
+  return found;
+}
+
+export function installed() {
+  return ADAPTERS
+    .filter((a) => (CLIS[a.id] || []).some(onPath))
+    .map((a) => ({ id: a.id, name: a.name, why: 'installed on this machine' }));
+}
+
+// What attach should turn on: everything this repo shows signs of, and Claude
+// Code either way, since it is the one that has been run end to end.
+//
+//   --agent=cursor,gemini   exactly these
+//   --agent=all             every adapter there is
+export function choose(repo, argv = []) {
+  const flag = argv.find((a) => a.startsWith('--agent='));
+  if (flag) {
+    const want = flag.slice('--agent='.length).split(',').map((s) => s.trim()).filter(Boolean);
+    if (want.includes('all')) return { chosen: ADAPTERS, unknown: [] };
+    const chosen = want.map(byId).filter(Boolean);
+    return { chosen, unknown: want.filter((w) => !byId(w)) };
+  }
+  const ids = new Set(['claude-code', ...detect(repo).map((d) => d.id)]);
+  return { chosen: ADAPTERS.filter((a) => ids.has(a.id)), unknown: [] };
+}

package/scripts/hook.mjs

@@ -1,7 +1,12 @@
 #!/usr/bin/env node
-// One Claude Code hook event, forwarded to the Nearly.
+// One agent hook event, forwarded to the Nearly.
 //
-//   node scripts/hook.mjs <event> <repo-name>
+//   node scripts/hook.mjs <event> <repo-name> [--adapter=<id>]
+//
+// <event> is always one of Nearly's own names (pre-tool, stop, ...) because
+// attach picks it when it writes the hook. --adapter names whose dialect is
+// arriving on stdin; without one, Claude Code's is assumed and the payload is
+// forwarded untouched, which keeps the oldest path the simplest one.
 //
 // Claude Code writes the event as JSON on stdin and reads our answer from
 // stdout. We sit in between so the server does not have to be running before
@@ -20,15 +25,22 @@
 import { spawn } from 'node:child_process';
 import { join, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { byId } from '../server/adapters.mjs';
 
 const HOST = '127.0.0.1';
 const PORT = Number(process.env.NEARLY_PORT || 47653);
 const BASE = `http://${HOST}:${PORT}`;
 const root = join(dirname(fileURLToPath(import.meta.url)), '..');
 
-const [, , event, name = 'repo'] = process.argv;
+const args = process.argv.slice(2);
+const flag = args.find((a) => a.startsWith('--adapter='));
+const positional = args.filter((a) => !a.startsWith('--'));
+const [event, name = 'repo'] = positional;
 if (!event) process.exit(0);
 
+// An unknown id is a typo in a config file, not a reason to wedge the agent.
+const adapter = flag ? byId(flag.slice('--adapter='.length)) : null;
+
 const body = await new Promise((r) => {
   let s = '';
   process.stdin.setEncoding('utf8');
@@ -65,14 +77,37 @@ if (!(await up()) && !(await start())) process.exit(0);   // fail open, silently
 // stall the agent.
 const budget = event === 'pre-tool' ? 600_000 : 15_000;
 
+// Translate on the way in. A payload we cannot parse is forwarded as it came,
+// so a harness that changes its shape degrades to Claude Code's rather than to
+// nothing.
+let payload = body || '{}';
+if (adapter && adapter.normalize) {
+  try { payload = JSON.stringify(adapter.normalize(event, JSON.parse(body || '{}'))); }
+  catch { /* keep the original */ }
+}
+
 try {
-  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}`, {
+  const hold = adapter?.holdMs ? `&hold=${adapter.holdMs}` : '';
+  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}${hold}`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
-    body: body || '{}',
+    body: payload,
     signal: AbortSignal.timeout(budget),
   });
   const text = await res.text();
+
+  // ...and on the way out. Rendering is what makes a deny actually land: half of
+  // these harnesses would read Claude Code's answer as no answer at all, and an
+  // unread deny is a gate that reports success while allowing everything.
+  if (adapter && adapter.render) {
+    let answer = {};
+    try { answer = JSON.parse(text || '{}'); } catch { /* treat as no answer */ }
+    const out = adapter.render(event, answer);
+    if (out.stderr) process.stderr.write(out.stderr);
+    if (out.stdout) process.stdout.write(out.stdout);
+    process.exit(out.exit || 0);
+  }
+
   if (text && text !== '{}') process.stdout.write(text);
 } catch { /* fail open */ }
 

package/scripts/push-record.mjs

@@ -15,10 +15,14 @@ import { paths } from '../server/paths.mjs';
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const repo = resolve(process.argv[2] || '.');
 function configured() {
-  try {
-    const f = join(root, '.nearly.json');
-    if (existsSync(f)) return JSON.parse(readFileSync(f, 'utf8')).urlBase || '';
-  } catch { /* fall through to the env var */ }
+  for (const f of [paths.config(), join(root, '.nearly.json')]) {
+    try {
+      if (existsSync(f)) {
+        const u = JSON.parse(readFileSync(f, 'utf8')).urlBase;
+        if (u) return u;
+      }
+    } catch { /* try the next one */ }
+  }
   return '';
 }
 const URL_BASE = (process.env.NEARLY_URL_BASE || configured() || '').replace(/\/$/, '');