nearly-cli 0.1.17 → 0.1.18

package/README.md

@@ -146,8 +146,10 @@ npx nearly-cli
 
   · 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)
+  · Claude Code sessions opened in another folder are gated too, once they work in this repo
+  · restart any Claude Code or Cursor session already open — hooks are read when a session starts
   · upgrades reach this repo automatically
-  · the record is offered when you push
+  · the record is added to #12 on your next push — sessions from now on
 
   Now just work. Requests that need you appear at http://127.0.0.1:47653
   Nothing to leave running. Turn it off again with --off.
@@ -159,6 +161,25 @@ Nothing to configure, no server to start, and `nearly off` removes all of it.
 Run it again in any other repo you want recorded. After the first time the
 command is just `nearly`.
 
+Three things that are easy to miss, and that the command now says out loud:
+
+- **Only sessions from now on.** A session already open keeps the hooks it
+  started with, which here means none. Restart it.
+- **The record reaches a pull request on a push.** Turning Nearly on for a branch
+  whose pull request already exists changes nothing on that pull request until
+  you push again. If that pull request is already merged, open a new one.
+- **Sessions opened somewhere else are covered.** Claude Code only reads a repo's
+  hooks for a session started in that repo, so a session opened one folder up —
+  a parent folder, a monorepo root, your home directory — used to edit the repo
+  with nothing gated and nothing recorded, while `nearly doctor` said all was
+  well. `nearly` now also adds one hook to Claude Code's user settings
+  (`~/.claude/settings.json`). It stays silent unless a call works in a repo
+  Nearly is on for; from then on that session is gated like one started there,
+  including calls that never mention the repo. Sessions that have nothing to do
+  with it pay a process start per tool call and never reach a server. It is
+  removed when you turn Nearly off for the last repo, and `nearly --local-only`
+  skips it.
+
 ### Where it installs
 
 `npx nearly-cli` installs a copy into `~/.nearly/runtime`, and the hooks call
@@ -472,6 +493,7 @@ The claim this project makes is testable: a reviewer who sees the session record
 - `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/outside.mjs`, the hook in Claude Code's user settings that gates sessions opened in another folder
 - `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`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "nearly-cli",
-  "version": "0.1.17",
+  "version": "0.1.18",
   "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/detect.test.mjs test/adapters.test.mjs test/spawn.test.mjs test/stale-server.test.mjs test/runtime.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 test/stale-server.test.mjs test/outside.test.mjs test/runtime.test.mjs"
   }
 }

package/scripts/attach.mjs

@@ -13,6 +13,8 @@
 //   · 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
+//   · one hook in Claude Code's user settings, so a session opened in another
+//     folder is gated when it works in this repo (--local-only to skip it)
 //
 // There is no server to remember. The hooks start it the first time they need
 // it, and if it cannot start, Claude Code falls back to its own prompts and
@@ -26,6 +28,8 @@ import { dataRoot, paths } from '../server/paths.mjs';
 import { choose, installed as agentsOnMachine } from './detect.mjs';
 import { installRuntime, hasRuntime, isRuntime, runtimeCommand } from './runtime.mjs';
 import { ADAPTERS } from '../server/adapters.mjs';
+import { installOutside, removeOutside, attachedRepos, userSettingsFile } from './outside.mjs';
+import { prForBranch } from './pr-state.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const HOOK = join(root, 'scripts', 'hook.mjs');
@@ -146,6 +150,7 @@ const off = argv.includes('--off') || argv.includes('--detach');
 // Now the never-rules block with nobody present, everything else is done and
 // recorded, and holding for approval is something you turn on while watching.
 const supervise = argv.includes('--supervise');
+const localOnly = argv.includes('--local-only');
 const auto = !supervise;
 // The repo is wherever git says its top is. Looking only for a .git folder in
 // the current directory rejected every subfolder, which is where people usually
@@ -259,6 +264,24 @@ try {
   notes.push(`could not remember this repo for the dashboard: ${e.message}`);
 }
 
+// ---------------------------------------------------------------------------
+// Sessions opened in another folder
+// ---------------------------------------------------------------------------
+// Claude Code only reads this repo's hooks when a session starts here. The hook
+// in its user settings covers the rest, and stays only while some repo still
+// has Nearly on. Never from a pinned npx call: that would put a registry lookup
+// in front of every tool call in every session on the machine.
+let reach = null;
+const claudeWired = wired.some((a) => a.id === 'claude-code');
+if (!off && claudeWired && !localOnly && (installed || runtime || !fromPackage)) {
+  try {
+    reach = installOutside((ev) => hookCmd(ev));
+    if (reach.error) { notes.push(`sessions opened in other folders are not covered: ${reach.error}`); reach = null; }
+  } catch (e) { notes.push(`sessions opened in other folders are not covered: ${e.message}`); }
+} else if (off || localOnly) {
+  try { if (!attachedRepos().length) removeOutside(); } catch { /* leave it: it answers nothing without repos */ }
+}
+
 // ---------------------------------------------------------------------------
 // A server from somewhere else, already holding the port
 // ---------------------------------------------------------------------------
@@ -347,6 +370,7 @@ if (off) {
     ? `  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(dim('  restart any agent session open here; it keeps the hooks it started with'));
   console.log('');
   process.exit(0);
 }
@@ -364,9 +388,30 @@ 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}`);
 }
+if (reach) {
+  console.log(`  ${ok('·')} Claude Code sessions opened in another folder are gated too, once they work in this repo`);
+  console.log(`    ${dim(`a hook in ${userSettingsFile().replace(process.env.HOME || '~', '~')}; it stays silent everywhere else`)}`);
+} else if (claudeWired && !off) {
+  console.log(`  ${ok('·')} ${dim('only Claude Code sessions started in this folder are gated')}`);
+}
+// Hooks are read when a session starts. Someone who turns this on and carries on
+// in the window they already had is not gated at all, and nothing says so.
+if (wired.length) {
+  console.log(`  ${bold('·')} ${bold(`restart any ${wired.map((a) => a.name).join(' or ')} session already open`)} ${dim('— hooks are read when a session starts')}`);
+}
 console.log(`  ${ok('·')} ${dim(updateNote())}`);
 if (push.status === 0) {
-  console.log(`  ${ok('·')} the record is offered when you push`);
+  // Only sessions from now on are recorded, and the record reaches a pull
+  // request on a push. Said here, because the natural thing is to look at a pull
+  // request that already exists and wonder where the record is.
+  const pr = prForBranch(repo);
+  if (pr.state === 'open') {
+    console.log(`  ${ok('·')} the record is added to #${pr.number} on your next push ${dim('— sessions from now on')}`);
+  } else if (pr.state === 'merged' || pr.state === 'closed') {
+    console.log(`  ${ok('·')} the record is offered on your next push ${dim(`— #${pr.number} for this branch is ${pr.state}, so open a new pull request first`)}`);
+  } else {
+    console.log(`  ${ok('·')} the record is offered on your next push ${dim('— sessions from now on, once a pull request is open')}`);
+  }
 } else {
   // All of it: when a pre-push hook of yours is already there, the lines after
   // the first are the ones that say how to add Nearly to it by hand.

package/scripts/doctor.mjs

@@ -17,6 +17,8 @@ import { fileURLToPath } from 'node:url';
 import { execFileSync, spawnSync } from 'node:child_process';
 import { paths, dataRoot } from '../server/paths.mjs';
 import { ADAPTERS, OURS_RE } from '../server/adapters.mjs';
+import { outsideInstalled } from './outside.mjs';
+import { prForBranch } from './pr-state.mjs';
 
 const root = resolve(join(dirname(fileURLToPath(import.meta.url)), '..'));
 const repo = resolve(process.argv.slice(2).find((a) => !a.startsWith('--')) || process.cwd());
@@ -122,6 +124,13 @@ if (gated.length) {
   }
 }
 
+// A repo's own hooks only run for sessions started in it. Everything above can
+// be green while every session is opened one folder up and none of it is seen.
+if (gated.some((a) => a.id === 'claude-code')) {
+  if (outsideInstalled()) say(true, 'sessions opened in other folders', 'gated once they work in this repo');
+  else say(null, 'sessions opened in other folders', 'not gated — only Claude Code sessions started in this folder are. Run `nearly` here to cover them');
+}
+
 // 3 — the server, and whether it is this build
 let health = null;
 try {
@@ -207,14 +216,11 @@ if (!ghOk) {
   const auth = spawnSync('gh', ['auth', 'status'], { encoding: 'utf8' }).status === 0;
   say(auth, 'GitHub CLI (gh)', auth ? 'installed and signed in' : 'installed but not signed in', 'run `gh auth login`');
   if (auth) {
-    const pr = spawnSync('gh', ['pr', 'view', '--json', 'number,url'], { cwd: repo, encoding: 'utf8' });
-    if (pr.status === 0) {
-      let url = '';
-      try { url = JSON.parse(pr.stdout).url; } catch { /* keep it blank */ }
-      say(true, 'open pull request', url);
-    } else {
-      say(null, 'open pull request', `none for ${branch} — raise one, then push again`);
-    }
+    const pr = prForBranch(repo);
+    if (pr.state === 'open') say(true, 'open pull request', pr.url);
+    else if (pr.state === 'merged' || pr.state === 'closed') {
+      say(null, 'open pull request', `none — #${pr.number} for ${branch} is ${pr.state}. Open a new one, then push again`);
+    } else say(null, 'open pull request', `none for ${branch} — raise one, then push again`);
   }
 }
 

package/scripts/hook.mjs

@@ -37,7 +37,8 @@ const root = join(dirname(fileURLToPath(import.meta.url)), '..');
 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;
+const [event] = positional;
+let name = positional[1] || 'repo';
 if (!event) process.exit(0);
 
 // An unknown id is a typo in a config file, not a reason to wedge the agent.
@@ -45,7 +46,9 @@ const adapter = flag ? byId(flag.slice('--adapter='.length)) : null;
 // Nobody is at the keyboard. Set by attach --auto, carried per repo rather than
 // as machine-wide state, because supervising one project and not another is the
 // normal case.
-const unattended = args.includes('--auto');
+let unattended = args.includes('--auto');
+// Written into Claude Code's user settings rather than a repo's: see outside.mjs.
+const outside = args.includes('--outside');
 
 const body = await new Promise((r) => {
   let s = '';
@@ -87,6 +90,28 @@ async function start() {
   return false;
 }
 
+// A session opened somewhere else. Decide whether this call is any of our
+// business before doing anything that costs more than reading a few small files.
+// Nothing goes to a server unless the answer is yes.
+let extra = '';
+if (outside) {
+  let hook = {};
+  try { hook = JSON.parse(body || '{}'); } catch { /* nothing to go on */ }
+  const { attachedRepos, concerns, launchedIn, rememberedRepo } = await import('./outside.mjs');
+  const repos = attachedRepos();
+  if (!repos.length) process.exit(0);
+  // Started in one of them: its own hooks are running, and answering twice would
+  // record every call twice. A subfolder is not certain to load them, so there
+  // both fire and the server keeps whichever arrives first.
+  if (repos.some((r) => r.real === launchedIn(hook))) process.exit(0);
+  const hit = ((event === 'pre-tool' || event === 'post-tool') ? concerns(hook, repos) : null)
+    || rememberedRepo(hook.session_id, repos);
+  if (!hit) process.exit(0);
+  name = hit.name;
+  unattended = hit.auto;
+  extra = `&outside=1&repo=${encodeURIComponent(hit.repo)}`;
+}
+
 let health = await up();
 if (health === 'stale') {
   // Take the port back rather than run whatever is already there. Nobody reads
@@ -118,7 +143,7 @@ if (adapter && adapter.normalize) {
 try {
   const hold = adapter?.holdMs ? `&hold=${adapter.holdMs}` : '';
   const auto = unattended ? '&auto=1' : '';
-  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}${hold}${auto}`, {
+  const res = await fetch(`${BASE}/hooks/${event}?attach=${encodeURIComponent(name)}${hold}${auto}${extra}`, {
     method: 'POST',
     headers: { 'content-type': 'application/json' },
     body: payload,

package/scripts/outside.mjs

@@ -0,0 +1,173 @@
+// Sessions opened somewhere else.
+//
+// Claude Code reads a repo's .claude/settings.local.json only when a session is
+// started in that repo. Open it one folder up — a parent folder, a monorepo
+// root, your home directory — and edit the repo from there, and the repo's hooks
+// never run. Nothing was recorded, nothing was refused, and `nearly doctor`,
+// which checks the repo, said everything was fine. That was found by the person
+// who built this, which is how sure we can be that everyone else will hit it.
+//
+// So attach also writes one hook into Claude Code's user settings, which every
+// session reads. It is silent unless a call touches a repo Nearly is on for:
+//
+//   - a session started in such a repo already has that repo's own hooks, so
+//     this one steps aside;
+//   - a call whose working directory or file is inside such a repo is gated and
+//     recorded as that repo's, with that repo's own settings (--auto or not);
+//   - once a session has been gated this way, the rest of its calls are too —
+//     `rm -rf ~` does not mention the repo, and a gate that only looked at the
+//     repo's own paths would wave it through;
+//   - anything else answers nothing and costs a process start.
+//
+// The repo's own hook config stays the source of truth. The user-level hook
+// holds no list of its own; it reads which repos are on, and how, from the
+// repos themselves.
+
+import { readFileSync, existsSync, realpathSync, writeFileSync, mkdirSync } from 'node:fs';
+import { join, dirname, resolve, sep, isAbsolute } from 'node:path';
+import { homedir } from 'node:os';
+import { paths } from '../server/paths.mjs';
+import { OURS_RE, isOurs } from '../server/adapters.mjs';
+
+// Claude Code's user settings. CLAUDE_CONFIG_DIR moves them, and is also how the
+// tests keep this away from the real file.
+export const userSettingsFile = () =>
+  join(process.env.CLAUDE_CONFIG_DIR || join(homedir(), '.claude'), 'settings.json');
+
+// The events worth hearing from a session opened elsewhere. SessionStart says
+// nothing about where the session will work, so it is left out.
+export const OUTSIDE_EVENTS = {
+  UserPromptSubmit: 'prompt', PreToolUse: 'pre-tool', PostToolUse: 'post-tool',
+  Stop: 'stop', SessionEnd: 'session-end',
+};
+
+const fold = (p) => (process.platform === 'win32' ? p.toLowerCase() : p);
+
+// The real path of p, or of its nearest existing parent with the rest appended:
+// a file the agent is about to create does not exist yet, and still belongs to
+// the repo it is being created in.
+export function realish(p) {
+  if (!p) return null;
+  let abs = resolve(String(p).replace(/^~(?=$|[\\/])/, homedir()));
+  const tail = [];
+  for (;;) {
+    try { return fold(join(realpathSync.native(abs), ...tail.reverse())); }
+    catch {
+      const up = dirname(abs);
+      if (up === abs) return fold(resolve(p));
+      tail.push(abs.slice(up.length).replace(/^[\\/]/, ''));
+      abs = up;
+    }
+  }
+}
+
+export const inside = (child, parent) =>
+  !!child && !!parent && (child === parent || child.startsWith(parent.endsWith(sep) ? parent : parent + sep));
+
+// The repos Nearly is on for with Claude Code, and how each was turned on. A repo
+// in the list whose hooks have since been removed by hand is not one.
+export function attachedRepos() {
+  let list = [];
+  try { list = JSON.parse(readFileSync(paths.repos(), 'utf8')); } catch { return []; }
+  const out = [];
+  for (const repo of Array.isArray(list) ? list : []) {
+    let cmd = null;
+    try {
+      const s = JSON.parse(readFileSync(join(repo, '.claude', 'settings.local.json'), 'utf8').replace(/^\uFEFF/, ''));
+      cmd = (s.hooks?.PreToolUse || []).flatMap((e) => e.hooks || []).map((h) => h.command)
+        .find((c) => typeof c === 'string' && OURS_RE.test(c));
+    } catch { continue; }
+    if (!cmd) continue;
+    const name = (cmd.match(/\bpre-tool\s+([a-z0-9-]+)/i) || [])[1] || 'repo';
+    out.push({ repo, real: realish(repo), name, auto: /\s--auto\b/.test(cmd) });
+  }
+  return out;
+}
+
+// Every path a call names: where it runs, the file it reads or writes, and any
+// absolute or home-relative path in a shell command.
+function pathsOf(hook) {
+  const found = [];
+  const i = hook.tool_input || {};
+  for (const k of ['file_path', 'path', 'notebook_path']) if (typeof i[k] === 'string') found.push(isAbsolute(i[k]) ? i[k] : resolve(hook.cwd || '.', i[k]));
+  if (hook.cwd) found.push(hook.cwd);
+  if (typeof i.command === 'string') {
+    // Rough on purpose. Reading a path that is not one costs a gated call at
+    // worst; missing one that is lets the call through ungated.
+    const words = i.command.split(/[\s;|&<>()]+/).map((w) => w.replace(/^[^\w~./\\:-]+|["']+$/g, '').replace(/^["']+/, '')).filter(Boolean);
+    words.forEach((w, n) => {
+      const afterCd = /^(?:cd|pushd)$/.test(words[n - 1] || '');
+      if (/^(?:~|\/|[A-Za-z]:[\\/])/.test(w)) found.push(w);
+      else if (afterCd || /[\\/]/.test(w)) found.push(resolve(hook.cwd || '.', w));
+    });
+  }
+  return found;
+}
+
+// The attached repo this call touches, if any.
+export function concerns(hook, repos) {
+  const touched = pathsOf(hook).map(realish);
+  return repos.find((r) => touched.some((p) => inside(p, r.real))) || null;
+}
+
+// Sessions already gated this way are remembered by the server; see marks.mjs.
+export { rememberOutside, rememberedRepo } from '../server/marks.mjs';
+
+// Where the session was started. Claude Code tells hooks outright; the payload's
+// cwd is the fallback, and is the same place until the agent changes directory.
+export const launchedIn = (hook) => realish(process.env.CLAUDE_PROJECT_DIR || hook.cwd);
+
+// ---------------------------------------------------------------------------
+// Writing and removing the user-level hook
+// ---------------------------------------------------------------------------
+
+function readSettings(file) {
+  if (!existsSync(file)) return null;
+  try { return JSON.parse(readFileSync(file, 'utf8').replace(/^\uFEFF/, '')); }
+  catch { return undefined; }   // present but unreadable: never overwrite it
+}
+
+const outsideEntry = (e) => isOurs(e) && /--outside\b/.test(JSON.stringify(e));
+
+// cmdFor(event) is the same command the repo hooks run, without a repo name.
+export function installOutside(cmdFor) {
+  const file = userSettingsFile();
+  const s = readSettings(file);
+  if (s === undefined) return { error: `${file} could not be read, so it was left alone` };
+  const settings = s || {};
+  const hooks = settings.hooks || {};
+  for (const ev of Object.keys(hooks)) {
+    const kept = (hooks[ev] || []).filter((e) => !outsideEntry(e));
+    if (kept.length) hooks[ev] = kept; else delete hooks[ev];
+  }
+  for (const [their, ours] of Object.entries(OUTSIDE_EVENTS)) {
+    hooks[their] = [...(hooks[their] || []),
+      { hooks: [{ type: 'command', command: `${cmdFor(ours)} --outside`, timeout: ours === 'pre-tool' ? 600 : ours === 'session-end' ? 120 : 30 }] }];
+  }
+  settings.hooks = hooks;
+  mkdirSync(dirname(file), { recursive: true });
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { file };
+}
+
+export function removeOutside() {
+  const file = userSettingsFile();
+  const settings = readSettings(file);
+  if (!settings || !settings.hooks) return { removed: false };
+  let removed = false;
+  for (const ev of Object.keys(settings.hooks)) {
+    const before = settings.hooks[ev] || [];
+    const kept = before.filter((e) => !outsideEntry(e));
+    if (kept.length !== before.length) removed = true;
+    if (kept.length) settings.hooks[ev] = kept; else delete settings.hooks[ev];
+  }
+  if (!removed) return { removed: false };
+  if (!Object.keys(settings.hooks).length) delete settings.hooks;
+  writeFileSync(file, JSON.stringify(settings, null, 2) + '\n');
+  return { removed: true, file };
+}
+
+export function outsideInstalled() {
+  const s = readSettings(userSettingsFile());
+  return !!(s && s.hooks && Object.values(s.hooks).some((list) => (list || []).some(outsideEntry)));
+}

package/scripts/pr-state.mjs

@@ -0,0 +1,20 @@
+// The pull request for the branch you are on, and whether it can still take a record.
+//
+// `gh pr view` finds a branch's pull request whatever state it is in. Everything
+// here used to read "found" as "open", so doctor reported a merged pull request
+// as the open one, and a push offered to post a record onto a conversation that
+// had already ended — where nobody reviewing will ever see it.
+
+import { spawnSync } from 'node:child_process';
+
+export function prForBranch(repo) {
+  if (spawnSync('gh', ['--version'], { encoding: 'utf8' }).status !== 0) return { state: 'no-gh' };
+  const r = spawnSync('gh', ['pr', 'view', '--json', 'number,url,state'], { cwd: repo, encoding: 'utf8', timeout: 15_000 });
+  if (r.status !== 0) {
+    return /not logged|authentication|gh auth/i.test(r.stderr || '') ? { state: 'signed-out' } : { state: 'none' };
+  }
+  try {
+    const { number, url, state } = JSON.parse(r.stdout);
+    return { state: String(state || 'OPEN').toLowerCase(), number, url };
+  } catch { return { state: 'none' }; }
+}

package/scripts/push-record.mjs

@@ -108,16 +108,20 @@ if (!hasGh) {
   console.log('');
   process.exit(0);
 }
-const pr = spawnSync('gh', ['pr', 'view', '--json', 'number,url'], { cwd: repo, encoding: 'utf8' });
-if (pr.status !== 0) {
-  const why = /not logged|authentication|gh auth/i.test(pr.stderr || '')
+const { prForBranch } = await import('./pr-state.mjs');
+const pr = prForBranch(repo);
+if (pr.state !== 'open') {
+  const why = pr.state === 'signed-out'
     ? 'gh is installed but not signed in. Run `gh auth login`, then push again.'
-    : 'No open pull request for this branch yet. Raise one, then push again to attach the record.';
+    : pr.state === 'merged' || pr.state === 'closed'
+      // Posting onto a finished conversation reaches nobody who is reviewing.
+      ? `The pull request for this branch, #${pr.number}, is already ${pr.state}. Open a new one, then push again to attach the record.`
+      : 'No open pull request for this branch yet. Raise one, then push again to attach the record.';
   console.log(dim(`  ${why}`));
   console.log('');
   process.exit(0);
 }
-const prUrl = (() => { try { return JSON.parse(pr.stdout).url; } catch { return null; } })();
+const prUrl = pr.url || null;
 
 if (process.env.NEARLY_NO_TTY === '1' || !process.stdin.isTTY) {
   console.log(dim('  No terminal to ask on, so nothing was posted.'));

package/server/index.mjs

@@ -12,6 +12,7 @@ import { randomUUID } from 'node:crypto';
 import { fileURLToPath } from 'node:url';
 import { DEFAULT_TIER, ruleKey, classify as classifyWith } from './policy.mjs';
 import { paths } from './paths.mjs';
+import { rememberOutside } from './marks.mjs';
 
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const PORT = Number(process.env.NEARLY_PORT || 47653);
@@ -242,6 +243,24 @@ function modelFromTranscript(p) {
   return null;
 }
 
+// The most recent thing the person typed, from a Claude Code transcript.
+function promptFromTranscript(p) {
+  if (!p || !fs.existsSync(p)) return null;
+  try {
+    let last = null;
+    for (const l of fs.readFileSync(p, 'utf8').split('\n')) {
+      if (!l) continue;
+      let j; try { j = JSON.parse(l); } catch { continue; }
+      if (j.type !== 'user' || j.isMeta) continue;
+      const c = j.message?.content;
+      const text = typeof c === 'string' ? c
+        : Array.isArray(c) && !c.some((x) => x?.type === 'tool_result') ? c.filter((x) => x?.type === 'text').map((x) => x.text).join('\n') : '';
+      if (text && !/^<(?:command-|local-command|system-reminder)/.test(text.trim())) last = text;
+    }
+    return last;
+  } catch { return null; }
+}
+
 function turnDiff(cwd, base, maxLines = 200) {
   const from = base || 'HEAD';
   const numstat = git(cwd, ['diff', '--numstat', from]);
@@ -357,6 +376,8 @@ function decide(sid, id, decision, why, scope = 'once') {
   // asked gets the same answer; answering only the last one left the first hook
   // hanging until the agent's own timeout, which looks like the agent freezing.
   for (const r of p.responders) r(decision, why);
+  s.answered ||= new Map();
+  s.answered.set(id, [decision, why]);
   record(sid, { type: 'decision', id, decision, why, scope, tool: p.tool, key: p.key, waitedMs: Date.now() - p.at });
   if (s.pending.size === 0 && s.state === 'waiting') s.state = 'working';
   broadcast({ type: 'session-state', session: sid, state: s.state });
@@ -389,10 +410,30 @@ const server = http.createServer(async (req, res) => {
     try { hook = JSON.parse(await readBody(req) || '{}'); } catch { /* keep {} */ }
     const ev = url.pathname.slice('/hooks/'.length);
     const attach = url.searchParams.get('attach');
+    // From the hook in Claude Code's user settings: a session started outside the
+    // repo. With a repo it touched that repo; without one, it is ours only if an
+    // earlier call already made it so, and otherwise gets no answer at all.
+    const outside = url.searchParams.get('outside') === '1';
+    const outsideRepo = outside ? url.searchParams.get('repo') : null;
+    if (outside && !attach && !(hook.session_id && sessions.has(hook.session_id))) return hookOk(res);
     let sidResolved = sidParam;
-    if (!sidResolved && attach && hook.session_id) {
+    if (!sidResolved && (attach || outside) && hook.session_id) {
       sidResolved = hook.session_id;
-      if (!sessions.has(sidResolved)) attachSession({ id: sidResolved, name: attach.replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 24) || 'repo', cwd: hook.cwd || process.cwd() });
+      if (!sessions.has(sidResolved) && attach) {
+        const made = attachSession({ id: sidResolved, name: attach.replace(/[^a-z0-9-]/gi, '-').toLowerCase().slice(0, 24) || 'repo', cwd: outsideRepo || hook.cwd || process.cwd() });
+        // Its prompt went by before anything said the session was ours. The
+        // transcript still has it, and a record that starts mid-task without
+        // saying what was asked is missing the part a reviewer reads first.
+        if (outsideRepo) {
+          made.outside = true;
+          try { rememberOutside(sidResolved, outsideRepo); } catch { /* it is re-found by path next time */ }
+          // Later calls from this session may not mention the repo, and arrive
+          // without its settings; they keep the ones it was gated with.
+          made.auto = url.searchParams.get('auto') === '1';
+          const asked = promptFromTranscript(hook.transcript_path);
+          if (asked) { made.lastPrompt = { text: asked, at: Date.now() }; record(sidResolved, { type: 'prompt', text: asked.slice(0, 4000) }); }
+        }
+      }
     }
     const s = sessions.get(sidResolved);
     const sid = sidResolved;
@@ -410,7 +451,10 @@ const server = http.createServer(async (req, res) => {
       return hookOk(res);
     }
     if (ev === 'prompt') {
-      if (s) { s.state = 'working'; record(sid, { type: 'prompt', text: String(hook.prompt || '').slice(0, 4000) }); broadcast({ type: 'session-state', session: sid, state: s.state }); }
+      // The same prompt twice within a few seconds is one prompt heard by two hooks.
+      const text = String(hook.prompt || '');
+      const echo = s && s.lastPrompt && s.lastPrompt.text === text && Date.now() - s.lastPrompt.at < 5000;
+      if (s && !echo) { s.lastPrompt = { text, at: Date.now() }; s.state = 'working'; record(sid, { type: 'prompt', text: text.slice(0, 4000) }); broadcast({ type: 'session-state', session: sid, state: s.state }); }
       return hookOk(res);
     }
     if (ev === 'session-end') {
@@ -432,7 +476,7 @@ const server = http.createServer(async (req, res) => {
       // stalls the run and teaches people to turn the gate off. The never-rules
       // still bite, because those never needed a person. Everything that would
       // have been asked is done and written down instead.
-      const unattended = url.searchParams.get('auto') === '1';
+      const unattended = url.searchParams.get('auto') === '1' || (outside && !!s?.auto);
       let { tier, reason } = classifyWith(hook, rules);
       if (unattended && tier === 'ask') { tier = 'log'; reason = 'allowed unattended — nobody was asked'; }
       const id = hook.tool_use_id || randomUUID();
@@ -444,10 +488,22 @@ const server = http.createServer(async (req, res) => {
         hookSpecificOutput: { hookEventName: 'PreToolUse', permissionDecision: decision, permissionDecisionReason: `nearly: ${why}` },
       });
       if (!s) return respond('deny', 'unknown session');
-      if (tier === 'never') { record(sid, { type: 'decision', id, decision: 'deny', why: reason, scope: 'policy', tool: shown, input: hook.tool_input, tier, unattended }); return respond('deny', `never (${reason})`); }
+      // Already answered: the same call through a second hook — a repo's own and
+      // the user-level one, or VS Code reading two config files. Same answer,
+      // written down once.
+      if (hook.tool_use_id && s.answered?.has(id)) return respond(...s.answered.get(id));
+      const answer = (decision, why) => {
+        if (hook.tool_use_id) {
+          s.answered ||= new Map();
+          s.answered.set(id, [decision, why]);
+          if (s.answered.size > 500) s.answered.delete(s.answered.keys().next().value);
+        }
+        return respond(decision, why);
+      };
+      if (tier === 'never') { record(sid, { type: 'decision', id, decision: 'deny', why: reason, scope: 'policy', tool: shown, input: hook.tool_input, tier, unattended }); return answer('deny', `never (${reason})`); }
       if (tier === 'log') {
         record(sid, { type: 'decision', id, decision: 'allow', why: reason, scope: unattended ? 'auto' : 'policy', tool: shown, input: hook.tool_input, tier });
-        return respond('allow', unattended ? reason : `do and log (${reason})`);
+        return answer('allow', unattended ? reason : `do and log (${reason})`);
       }
       // ask: hold the response until the UI decides, or fail closed
       // A harness may say it will not wait as long as we would. It can shorten
@@ -470,10 +526,15 @@ const server = http.createServer(async (req, res) => {
     }
 
     if (ev === 'post-tool') {
-      if (s) record(sid, { type: 'post_tool', id: hook.tool_use_id, tool: hook.tool_label || hook.tool_name, duration_ms: hook.duration_ms, response: trim(hook.tool_response ?? '') });
+      const seen = s && hook.tool_use_id && s.posted?.has(hook.tool_use_id);
+      if (s && hook.tool_use_id) { s.posted ||= new Set(); s.posted.add(hook.tool_use_id); if (s.posted.size > 500) s.posted.delete(s.posted.values().next().value); }
+      if (s && !seen) record(sid, { type: 'post_tool', id: hook.tool_use_id, tool: hook.tool_label || hook.tool_name, duration_ms: hook.duration_ms, response: trim(hook.tool_response ?? '') });
       return hookOk(res);
     }
     if (ev === 'stop') {
+      // One turn ending, heard by two hooks, is still one turn.
+      if (s && s.attached && s.lastStopAt && Date.now() - s.lastStopAt < 3000) return hookOk(res);
+      if (s && s.attached) s.lastStopAt = Date.now();
       if (s && s.attached) {
         s.turns += 1;
         s.state = 'idle';

package/server/marks.mjs

@@ -0,0 +1,40 @@
+// Claude Code sessions opened outside a repo, remembered once they have been
+// gated in it. Written by the server, read by the hook (scripts/outside.mjs).
+
+import { readFileSync, writeFileSync, mkdirSync, readdirSync, statSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { paths } from './paths.mjs';
+
+// One small file per session, naming the repo.
+//
+// Later calls from such a session may not mention the repo at all, and still
+// have to be gated. Asking the server would put a network round trip in front of
+// every tool call of every Claude Code session on the machine, and asking one
+// from an older build got every one of those calls refused as an unknown
+// session. A file lookup costs neither.
+const safeId = (sid) => String(sid || '').replace(/[^A-Za-z0-9_-]/g, '').slice(0, 80);
+const WEEK = 7 * 24 * 60 * 60 * 1000;
+
+export function rememberOutside(sid, repo) {
+  const id = safeId(sid);
+  if (!id) return;
+  const dir = paths.outside();
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, id), String(repo));
+  try {
+    for (const f of readdirSync(dir)) {
+      const full = join(dir, f);
+      if (Date.now() - statSync(full).mtimeMs > WEEK) rmSync(full, { force: true });
+    }
+  } catch { /* tidying is optional */ }
+}
+
+export function rememberedRepo(sid, repos) {
+  const id = safeId(sid);
+  if (!id) return null;
+  try {
+    const repo = readFileSync(join(paths.outside(), id), 'utf8').trim();
+    return repos.find((r) => r.repo === repo) || null;
+  } catch { return null; }
+}
+

package/server/paths.mjs

@@ -60,4 +60,7 @@ export const paths = {
   // with no link. Same lesson as recordings — anything a person configured
   // belongs in their space, not in ours.
   config: () => dataFile('NEARLY_CONFIG', 'config.json'),
+  // Claude Code sessions opened outside a repo that have been gated in it, so the
+  // hook can keep gating them without asking the server. See scripts/outside.mjs.
+  outside: () => process.env.NEARLY_OUTSIDE || join(dataRoot, 'outside'),
 };