Merge remote-tracking branch 'origin/327-claude-code-hooks' into fix/327-transcript-source-guards

# Conflicts:
#	CHANGELOG.md

Author: rahilp

CHANGELOG.md

@@ -30,6 +30,14 @@ All notable changes to Second Brain are documented here. Version numbers match `
 
 **Claude Code hooks (#327)**
 
+- SessionStart recall sent `?q=`; the route reads `query`. The hook printed nothing on every session start since it shipped.
+- SessionEnd parsed stdin as the transcript; Claude Code sends a `transcript_path`. Sessions were never captured. The hook now reads the JSONL transcript, keeps only human-readable turns, and captures behind a content gate.
+- Hooks now exit 1 with one stderr line on any failure; Claude Code hides stderr from exit-0 hooks.
+- `install.sh` reconciles instead of appending, refuses a malformed settings.json, sets the SessionEnd `timeout` the 1.5 s hook budget requires, and keeps credentials in `~/.config/second-brain/config.json` rather than the hook command line.
+- New: `install.sh --check` and `--uninstall`.
+- Session capture redacts credentials from the body before sending it — your own token, `Bearer` values, `sk-`/`ghp_`/`github_pat_`/`xoxb-`/`AKIA`/`AIza` key shapes, PEM private keys and `TOKEN=`-style assignments — while leaving UUIDs, commit SHAs, paths and ordinary prose intact.
+- SessionStart caches the block it printed and re-emits it on compaction, so compaction costs no recall at all; it falls back to a live recall when there is no cache or it is over 24 h old.
+- New: `install.ps1`, a PowerShell installer for Windows machines where Claude Code runs hooks under PowerShell rather than Git Bash.
 - Worker: a Claude Code transcript is never merged into, never replaces, and never deprecates a memory written by any other source; it is stored as a duplicate-candidate or a draft instead. Transcripts are excluded from insight synthesis.
 - Worker: capturing a near-duplicate of a protected memory (importance ≥ 4 or canonical) now stores the newcomer as a duplicate-candidate. It used to report success with an id that did not exist.
 

README.md

@@ -175,6 +175,7 @@ A successful response looks like `{"ok":true,"id":"..."}`.
 - **Notes:** [Second Brain Sync for Obsidian](https://community.obsidian.md/plugins/second-brain-sync) and Notion
 - **Calendar and email:** Google, Outlook, iCloud, and Gmail integrations
 - **iPhone and iPad:** Voice, text, and share-sheet shortcuts in [`integrations/ios-shortcuts/`](integrations/ios-shortcuts/)
+- **Claude Code:** session hooks that recall project context on start and save the conversation on exit — [`integrations/claude-code-hooks/`](integrations/claude-code-hooks/)
 - **Dashboard:** Capture, recall, browse, graph, share, back up, and restore from the built-in web interface
 
 See [Capture from Anywhere](wiki/Capture-from-Anywhere) for setup and usage instructions.

integrations/claude-code-hooks/README.md

@@ -0,0 +1,164 @@
+# Claude Code hooks
+
+Two hooks that connect a Claude Code session to your Second Brain: one recalls
+project context when a session opens, one saves the conversation when it closes.
+
+They are independent of the MCP server. Use either, or both.
+
+## What the hooks do
+
+| Event | Runs on | Action | Cost |
+|---|---|---|---|
+| `SessionStart` | `startup`, `clear`, `compact` | `GET /recall` for this project, prints up to 5 memories into the session | one recall (~1 s), none on compaction |
+| `SessionEnd` | every reason (`clear`, `resume`, `logout`, `prompt_input_exit`, `other`) | `POST /capture` with the tail of the conversation | one capture (embedding + often a model call), 30 s hook timeout |
+
+`resume` and `fork` are skipped on start: those transcripts already contain the
+earlier injection. `compact` is not skipped — compaction discards it.
+
+On `startup` and `clear` the block that was printed is cached under
+`$XDG_CACHE_HOME/second-brain/session-<session_id>.txt` (`~/.cache/…` by
+default). Compaction re-prints that file verbatim and makes no request at all:
+the session id survives compaction and rotates on `/clear`, so a cached block is
+always the current session's context. With no cache, or one older than 24 h,
+compaction falls back to a live recall.
+
+## Install, upgrade, check, uninstall
+
+```bash
+bash install.sh https://your-worker.workers.dev your-token   # install or upgrade
+bash install.sh                                             # reuse existing credentials, or prompt
+bash install.sh --check                                     # prove the hooks reach the Worker
+bash install.sh --uninstall                                 # remove only our entries
+```
+
+PowerShell, for Windows without Git Bash — same behaviour, same guarantees:
+
+```powershell
+.\install.ps1 -WorkerUrl https://your-worker.workers.dev -Token your-token
+.\install.ps1            # reuse existing credentials, or prompt
+.\install.ps1 -Check
+.\install.ps1 -Uninstall
+```
+
+Re-running is safe: the installer replaces its own entries in
+`~/.claude/settings.json` and preserves everything else. It refuses to write a
+settings file that is not valid JSON rather than overwriting it.
+
+**Restart any session that is already open.** Claude Code snapshots the hook
+config at startup, so a running session keeps the old wiring.
+
+## Where credentials live
+
+`~/.config/second-brain/config.json` (mode 600) — the same file the CLI and the
+desktop app use:
+
+```json
+{ "workerUrl": "https://your-worker.workers.dev", "authToken": "…" }
+```
+
+Nothing is written into `settings.json` and nothing is passed on the hook
+command line, so the token never appears in Claude Code's settings or in `ps`.
+`SECOND_BRAIN_URL` and `SECOND_BRAIN_TOKEN` in the environment take precedence
+when set.
+
+## What is sent
+
+Recall:
+
+```
+GET /recall?query=<project>+decisions+and+context&topK=5&workspace=personal&tag=<project>
+```
+
+with a `tag`-less second attempt if the tagged one returns nothing. With no
+project (a session opened in `$HOME`), one generic query limited to the last 14
+days is sent instead.
+
+Capture:
+
+```json
+{
+  "content": "Claude Code session <id> — <project>@<branch> — <date> (<reason>)\n\nUser: …\n\nAssistant: …",
+  "source": "claude-code",
+  "tags": ["<project>"],
+  "workspace": "personal"
+}
+```
+
+Before it is sent, the formatted body — header included — is scanned for
+credentials, and each one is replaced with `[redacted]`: your own configured
+token wherever it appears, `Bearer <token>` values, provider key shapes (`sk-`,
+`ghp_`/`gho_`, `github_pat_`, `xoxb-`/`xoxp-`, AWS `AKIA…`, Google `AIza…`),
+whole PEM private-key blocks, and `TOKEN=`/`SECRET=`/`PASSWORD=`/`API_KEY=`
+style assignments. Only those shapes: a UUID, a commit SHA, a file path and
+ordinary prose are left exactly as they were, because a memory redacted into
+uselessness is worse than no memory. Tool output — where secrets usually live —
+never reaches the body in the first place.
+
+The transcript is read backwards from the end until three human turns are in
+hand (1 MB ceiling), and only human-readable turns survive: `tool_use`,
+`tool_result` and `thinking` blocks, sidechain (subagent) lines, `isMeta` lines,
+compaction summaries and harness noise such as `<system-reminder>` or
+`<command-name>` are all dropped. The body is capped at 2000 characters, newest
+turns first.
+
+Set `SECOND_BRAIN_WORKSPACE=company` to write to the shared layer instead.
+Set `SECOND_BRAIN_DRY_RUN=1` to print the capture body instead of sending it.
+
+## The gate, and the Worker version
+
+A session is captured only when it contains at least one human turn of 40+
+characters and 200+ characters of conversation (the header does not count) — a
+two-word prompt and a wall of tool output is not a session worth keeping.
+
+Capture also requires **Worker 3.0 or newer** (`GET /health` reports the
+version, cached for 24 h). Against an older brain, recall still works and the
+capture is skipped with one notice per day. Deploy the Worker, then use the
+hooks.
+
+Opt out of either half:
+
+```bash
+SECOND_BRAIN_HOOK_RECALL=0    # no recall on session start
+SECOND_BRAIN_HOOK_CAPTURE=0   # no capture on session end
+```
+
+## Overlap with the MCP instructions
+
+`AI_Instructions/CLAUDE_INSTRUCTIONS.md` already tells the model to call `recall`
+at the start of every conversation. If you use those instructions with the MCP
+server, the SessionStart hook is a second, unprompted recall on the same topic.
+It is still useful — it runs before the first token and cannot be skipped — but
+if you would rather have only one, set `SECOND_BRAIN_HOOK_RECALL=0` and leave the
+MCP rule in place.
+
+The SessionEnd capture has no MCP equivalent and does not overlap with anything.
+
+## Failure lines you will see
+
+Hooks report failures on stderr and exit non-zero; Claude Code hides stderr from
+a hook that exits 0, which is why nothing is silent any more.
+
+| Line | Meaning |
+|---|---|
+| `[Second Brain] recall failed: HTTP 401 unauthorized — token rejected…` | the token is wrong or was rotated — re-run `install.sh` |
+| `[Second Brain] recall failed: HTTP 404 — is SECOND_BRAIN_URL / workerUrl the Worker origin?` | the URL points at something that is not the Worker root |
+| `[Second Brain] recall failed: no reply within 15s` | the Worker did not answer in time |
+| `[Second Brain] session capture failed: …` | same causes, on the capture call |
+| `SessionEnd hook [<cmd>] failed: …` | Claude Code's own wrapper around the line above |
+| `[Second Brain] session capture needs Worker 3.0+ …` | the brain has not been redeployed to v3; shown once a day |
+
+Nothing here blocks the session. A failed hook costs you the recall or the
+capture, not the conversation.
+
+## Windows
+
+The hooks run under Git Bash if it is installed; without it Claude Code falls
+back to PowerShell, where `install.sh` will not run. Use `install.ps1` there —
+it writes the same credentials file and the same `settings.json` entries, and
+Node does the JSON editing in both installers so the two cannot drift. The hook
+scripts themselves are plain Node and work either way once they are in
+`settings.json`.
+
+The credentials file is written with mode 600, which NTFS ignores; on Windows it
+is protected by the permissions of your user profile directory like any other
+file under `%USERPROFILE%`.

integrations/claude-code-hooks/check.js

@@ -0,0 +1,31 @@
+#!/usr/bin/env node
+'use strict';
+// `install.sh --check`: prove the hooks can reach the Worker and show what they would do.
+const path = require('node:path');
+const { loadCredentials, fetchWithTimeout, CONFIG_PATH } = require('./common');
+const start = require('./session-start');
+const end = require('./session-end');
+
+async function main() {
+  const creds = loadCredentials();
+  if (!creds) { console.error(`No credentials: set SECOND_BRAIN_URL/SECOND_BRAIN_TOKEN or write ${CONFIG_PATH}`); process.exit(1); }
+  const res = await fetchWithTimeout(`${creds.baseUrl}/health`, { headers: { Authorization: `Bearer ${creds.token}` } }, 10000);
+  if (!res.ok) { console.error(`GET /health → HTTP ${res.status}. Token or URL is wrong.`); process.exit(1); }
+  const health = await res.json();
+  const major = parseInt(String(health.version ?? '').split('.')[0], 10);
+  console.log(`Worker ${health.version} at ${creds.baseUrl} — recall: on; session capture: ${major >= 3 ? 'on' : 'off (needs 3.0+)'}`);
+
+  console.log('\n— session-start against this brain —');
+  await start.main();
+
+  console.log('\n— session-end dry run against the bundled sample transcript —');
+  process.env.SECOND_BRAIN_DRY_RUN = '1';
+  const fixture = path.join(__dirname, 'fixtures', 'sample-transcript.jsonl');
+  const fs = require('node:fs');
+  const turns = end.readTranscriptTail(fixture);
+  const body = end.buildCaptureBody(turns, { project: 'sample', sessionId: 'sample', reason: 'other', workspace: 'personal' });
+  console.log(JSON.stringify({ wouldCapture: end.shouldCapture(turns), tags: body.tags, contentPreview: body.content.slice(0, 200) }, null, 2));
+  if (process.exitCode) process.exit(process.exitCode);
+}
+
+main().catch((e) => { console.error(e?.message ?? e); process.exit(1); });

integrations/claude-code-hooks/common.js

@@ -0,0 +1,137 @@
+'use strict';
+// Shared by session-start.js, session-end.js and check.js. CommonJS on purpose:
+// the repo's package.json has no "type", and vitest can require() this file
+// (test/ui/graph-clusters.test.ts does the same with public/utils.js).
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const crypto = require('node:crypto');
+const { execFileSync } = require('node:child_process');
+
+const HOME = os.homedir();
+const CONFIG_PATH = path.join(HOME, '.config', 'second-brain', 'config.json');
+const CACHE_DIR = path.join(process.env.XDG_CACHE_HOME || path.join(HOME, '.cache'), 'second-brain');
+const HEALTH_TTL_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Credentials: env first (what the tests and `--check` use), then the file the
+ * CLI and the desktop installer already share. Nothing is ever read from the
+ * hook command line, so the token is not in settings.json and not in `ps`.
+ */
+function loadCredentials(env = process.env, configPath = CONFIG_PATH) {
+  const url = (env.SECOND_BRAIN_URL || '').trim();
+  const token = (env.SECOND_BRAIN_TOKEN || '').trim();
+  if (url && token) return { baseUrl: stripSlash(url), token };
+  try {
+    const cfg = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+    if (cfg && typeof cfg.workerUrl === 'string' && typeof cfg.authToken === 'string' && cfg.workerUrl && cfg.authToken) {
+      return { baseUrl: stripSlash(cfg.workerUrl), token: cfg.authToken };
+    }
+  } catch { /* absent or malformed: the hook has nothing to do */ }
+  return null;
+}
+
+function stripSlash(u) { return String(u).trim().replace(/\/+$/, ''); }
+
+/** "personal" unless the user explicitly asks for the shared layer. Anything else is personal. */
+function resolveWorkspace(env = process.env) {
+  return (env.SECOND_BRAIN_WORKSPACE || '').trim() === 'company' ? 'company' : 'personal';
+}
+
+/**
+ * Claude Code writes the hook payload to stdin and closes it. A TTY (someone
+ * running the script by hand) or a pipe that never closes (execFile in a test)
+ * must not hang the hook, so the read races a short timer.
+ */
+function readStdinJson(timeoutMs = 1500) {
+  if (process.stdin.isTTY) return Promise.resolve(null);
+  return new Promise((resolve) => {
+    let raw = '';
+    let done = false;
+    const finish = (value) => { if (!done) { done = true; clearTimeout(timer); resolve(value); } };
+    const timer = setTimeout(() => finish(parse(raw)), timeoutMs);
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (c) => { raw += c; if (raw.length > 65536) finish(parse(raw)); });
+    process.stdin.on('end', () => finish(parse(raw)));
+    process.stdin.on('error', () => finish(null));
+  });
+  function parse(s) { try { return s.trim() ? JSON.parse(s) : null; } catch { return null; } }
+}
+
+/** basename of the origin remote (without .git), else basename of cwd, else null for $HOME and /. */
+function parseProjectName(remoteUrl, cwd, home = HOME) {
+  const clean = (s) => s.toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '');
+  if (remoteUrl) {
+    const base = remoteUrl.trim().replace(/[/:]+$/, '').split(/[/:]/).pop().replace(/\.git$/i, '');
+    if (base) return clean(base) || null;
+  }
+  if (!cwd) return null;
+  const resolved = path.resolve(cwd);
+  if (resolved === path.resolve(home) || resolved === path.parse(resolved).root) return null;
+  return clean(path.basename(resolved)) || null;
+}
+
+function gitRemoteUrl(cwd) {
+  try {
+    return execFileSync('git', ['-C', cwd, 'remote', 'get-url', 'origin'], {
+      stdio: ['ignore', 'pipe', 'ignore'], timeout: 2000, encoding: 'utf8',
+    }).trim() || null;
+  } catch { return null; }
+}
+
+function fetchWithTimeout(url, init, ms) {
+  return fetch(url, { ...init, signal: AbortSignal.timeout(ms) });
+}
+
+/** The one visible channel: stderr + exit 1. Claude Code drops stderr from an exit-0 hook. */
+function fail(message) {
+  process.stderr.write(`[Second Brain] ${message}\n`);
+  process.exitCode = 1;
+}
+
+function hintFor(status) {
+  if (status === 401 || status === 403) return ' — token rejected; re-run integrations/claude-code-hooks/install.sh';
+  if (status === 404) return ' — is SECOND_BRAIN_URL / workerUrl the Worker origin?';
+  return '';
+}
+
+/** `dir` is only ever passed by tests, so nothing writes to the real cache during a run. */
+function cachePath(name, dir = CACHE_DIR) {
+  fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, name);
+}
+
+/** Worker major version from GET /health, cached per origin for 24 h. null when unknown. */
+async function workerMajorVersion({ baseUrl, token }, now = Date.now()) {
+  const file = cachePath(`health-${crypto.createHash('sha1').update(baseUrl).digest('hex').slice(0, 12)}.json`);
+  try {
+    const cached = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (cached && now - cached.checkedAt < HEALTH_TTL_MS && Number.isInteger(cached.major)) return cached.major;
+  } catch { /* no cache yet */ }
+  try {
+    const res = await fetchWithTimeout(`${baseUrl}/health`, { headers: { Authorization: `Bearer ${token}` } }, 5000);
+    if (!res.ok) return null;
+    const body = await res.json();
+    const major = parseInt(String(body?.version ?? '').split('.')[0], 10);
+    if (!Number.isInteger(major)) return null;
+    fs.writeFileSync(file, JSON.stringify({ major, version: body.version, checkedAt: now }));
+    return major;
+  } catch { return null; }
+}
+
+/** Emit `message` via fail() at most once per 24 h per key. Returns true when it fired. */
+function noticeOncePerDay(key, message, now = Date.now()) {
+  const file = cachePath(`notice-${key}`);
+  try {
+    if (now - fs.statSync(file).mtimeMs < HEALTH_TTL_MS) return false;
+  } catch { /* first time */ }
+  fs.writeFileSync(file, String(now));
+  fail(message);
+  return true;
+}
+
+module.exports = {
+  CONFIG_PATH, CACHE_DIR, HEALTH_TTL_MS,
+  loadCredentials, resolveWorkspace, readStdinJson, parseProjectName, gitRemoteUrl,
+  fetchWithTimeout, fail, hintFor, cachePath, workerMajorVersion, noticeOncePerDay,
+};