npm - backthread - Versions diffs - 0.5.1 → 0.7.0 - Mend

backthread 0.5.1 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (5) hide show

package/.claude-plugin/plugin.json +1 -2
package/commands/how.md +27 -0
package/dist-bundle/backthread.js +292 -211
package/hooks/hooks.json +11 -0
package/package.json +1 -1

package/.claude-plugin/plugin.json CHANGED Viewed

@@ -2,12 +2,11 @@
   "name": "backthread",
   "displayName": "Backthread",
   "description": "Backthread helps you understand your codebase while AI ships features. It captures the why behind every Claude Code session so you can ask \"how does X work?\" without digging through PRs.",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "author": {
     "name": "Backthread"
   },
   "homepage": "https://backthread.dev",
-  "hooks": "./hooks/hooks.json",
   "mcpServers": {
     "backthread": {
       "command": "node",

package/commands/how.md ADDED Viewed

@@ -0,0 +1,27 @@
+---
+description: Ask how or why something in THIS repo works — get a short, grounded, cited answer synthesized from your Backthread "How it works" decision log (the captured "why" the code doesn't contain), instead of digging through PRs or guessing.
+argument-hint: "<your question, e.g. how does auth work?>"
+disable-model-invocation: true
+---
+# /backthread:how — how does it work?
+Answers your "how/why does X work?" question about this repository from your
+Backthread decision log. The server retrieves the question-relevant captured
+decisions and synthesizes ONE short, grounded answer — every claim cited, anything
+inferred flagged, and a partial-coverage note when the log is thin. Read-only:
+nothing leaves the machine but the question.
+## Grounded answer
+!`BT="${CLAUDE_PLUGIN_ROOT}/dist-bundle/backthread.js"; if [ -f "$BT" ]; then node "$BT" how --cwd "$(pwd)" $ARGUMENTS; else npx backthread how --cwd "$(pwd)" $ARGUMENTS; fi`
+## Your task
+Relay the grounded answer above to the user **verbatim** — it is already written
+for them, with its inline [n] citations, its Sources list, and the diagram link.
+Do not re-answer from your own knowledge, re-run the command, or call any other
+tool. If the result says "not logged in", tell the user to run `backthread login`.
+If it says no repo could be determined, tell them to run from the repo directory or
+`backthread connect` it. If it leads with a partial-coverage caveat, keep that
+caveat in what you surface — do not present a partial answer as complete.

package/dist-bundle/backthread.js CHANGED Viewed

@@ -6892,109 +6892,6 @@ import { realpathSync } from "node:fs";
 // src/login.ts
 import { hostname } from "node:os";
-// src/loopback.ts
-import { createServer } from "node:http";
-import { randomBytes } from "node:crypto";
-function generateState() {
-  return base64url(randomBytes(32));
-}
-function base64url(bytes) {
-  return bytes.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
-}
-function validateCallback(method, rawUrl, expectedState) {
-  if ((method ?? "").toUpperCase() !== "GET") return { ok: false, reason: "bad_method" };
-  let url2;
-  try {
-    url2 = new URL(rawUrl ?? "", "http://127.0.0.1");
-  } catch {
-    return { ok: false, reason: "wrong_path" };
-  }
-  if (url2.pathname !== "/callback") return { ok: false, reason: "wrong_path" };
-  const errorParam = url2.searchParams.get("error");
-  if (errorParam) return { ok: false, reason: "error_param", error: errorParam };
-  const state = url2.searchParams.get("state");
-  if (state === null || state !== expectedState) return { ok: false, reason: "state_mismatch" };
-  const token = url2.searchParams.get("token");
-  if (!token || !/^backthread_pat_[A-Za-z0-9_-]+$/.test(token)) {
-    return { ok: false, reason: "missing_token" };
-  }
-  return { ok: true, token };
-}
-function resultPage(ok) {
-  const title = ok ? "You\u2019re connected" : "Something went wrong";
-  const body = ok ? "Backthread is now authorized on this device. You can close this tab and return to your terminal." : "Backthread couldn\u2019t finish authorizing this device. Close this tab and run <code>backthread login</code> again.";
-  return `<!doctype html><html><head><meta charset="utf-8"><title>${title}</title>
-<style>body{font:16px/1.5 system-ui,sans-serif;max-width:32rem;margin:18vh auto;padding:0 1.5rem;color:#18181b}
-h1{font-size:1.25rem}code{background:#f4f4f5;padding:.1em .3em;border-radius:4px}</style></head>
-<body><h1>${title}</h1><p>${body}</p></body></html>`;
-}
-function startLoopbackServer() {
-  return new Promise((resolveStart, rejectStart) => {
-    const state = generateState();
-    let outcome = null;
-    let onOutcome = null;
-    const deliver = (o) => {
-      if (outcome) return;
-      outcome = o;
-      onOutcome?.();
-    };
-    const server = createServer((req, res) => {
-      const result = validateCallback(req.method, req.url, state);
-      if (!result.ok && result.reason === "wrong_path") {
-        res.writeHead(404, { "Content-Type": "text/plain" });
-        res.end("not found");
-        return;
-      }
-      res.writeHead(result.ok ? 200 : 400, { "Content-Type": "text/html; charset=utf-8" });
-      res.end(resultPage(result.ok));
-      if (result.ok && result.token) {
-        deliver({ token: result.token });
-      } else {
-        deliver({
-          error: new Error(
-            result.reason === "error_param" ? `web app reported: ${result.error}` : `invalid callback (${result.reason})`
-          )
-        });
-      }
-    });
-    server.on("error", (err) => {
-      if (outcome === null && onOutcome === null) rejectStart(err);
-      else deliver({ error: err });
-    });
-    server.listen(0, "127.0.0.1", () => {
-      const addr = server.address();
-      const port = addr.port;
-      const close = () => {
-        try {
-          server.close();
-        } catch {
-        }
-      };
-      const waitForToken = (timeoutMs = 5 * 6e4) => new Promise((resolve, reject) => {
-        const finish = () => {
-          if (!outcome) return;
-          close();
-          if ("token" in outcome) resolve(outcome.token);
-          else reject(outcome.error);
-        };
-        const timer = setTimeout(() => {
-          close();
-          reject(new Error("timed out waiting for the browser to authorize this device"));
-        }, timeoutMs);
-        onOutcome = () => {
-          clearTimeout(timer);
-          finish();
-        };
-        if (outcome) {
-          clearTimeout(timer);
-          finish();
-        }
-      });
-      resolveStart({ port, state, waitForToken, close });
-    });
-  });
-}
 // src/urls.ts
 var DEFAULT_APP_URL = "https://app.backthread.dev";
 function appBaseUrl(env = process.env) {
@@ -7002,10 +6899,11 @@ function appBaseUrl(env = process.env) {
   if (override && override.trim().length > 0) return override.replace(/\/+$/, "");
   return DEFAULT_APP_URL;
 }
-function buildCliAuthUrl(port, state, env = process.env) {
+function buildCliAuthUrl(session, clientPubKey, env = process.env, label) {
   const u = new URL("/cli-auth", appBaseUrl(env));
-  u.searchParams.set("port", String(port));
-  u.searchParams.set("state", state);
+  u.searchParams.set("session", session);
+  u.searchParams.set("k", clientPubKey);
+  if (label && label.trim().length > 0) u.searchParams.set("label", label.trim());
   return u.toString();
 }
 var DEFAULT_WORKER_URL = "https://clew-ingest-worker.arpy-183.workers.dev";
@@ -7017,6 +6915,9 @@ function workerBaseUrl(env = process.env) {
 function buildInferDecisionsUrl(env = process.env) {
   return new URL("/infer-decisions", workerBaseUrl(env)).toString();
 }
+function buildGroundedAskUrl(env = process.env) {
+  return new URL("/grounded-ask", workerBaseUrl(env)).toString();
+}
 var DEFAULT_FUNCTIONS_URL = "https://yempemohevgpctkpstuf.supabase.co/functions/v1";
 function functionsBaseUrl(env = process.env) {
   const override = env.BACKTHREAD_FUNCTIONS_URL;
@@ -7026,12 +6927,12 @@ function functionsBaseUrl(env = process.env) {
 function buildIngestDecisionsUrl(env = process.env) {
   return new URL(`${functionsBaseUrl(env).replace(/\/+$/, "")}/ingest-decisions`).toString();
 }
-function buildReadDecisionsUrl(env = process.env) {
-  return new URL(`${functionsBaseUrl(env).replace(/\/+$/, "")}/read-decisions`).toString();
-}
 function buildOnboardingStateUrl(env = process.env) {
   return new URL(`${functionsBaseUrl(env).replace(/\/+$/, "")}/onboarding-state`).toString();
 }
+function buildCliAuthPollUrl(env = process.env) {
+  return new URL(`${functionsBaseUrl(env).replace(/\/+$/, "")}/cli-auth-poll`).toString();
+}
 function buildRepoDeepLink(owner, name, env = process.env) {
   const base = appBaseUrl(env);
   return `${base}/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`;
@@ -7278,22 +7179,117 @@ function configLocationHint(env) {
   return env.BACKTHREAD_CONFIG_DIR ? `${env.BACKTHREAD_CONFIG_DIR}/config.json` : "~/.backthread/config.json";
 }
+// src/cliAuthCrypto.ts
+import { createECDH, hkdfSync, createDecipheriv, randomBytes } from "node:crypto";
+var HKDF_SALT = Buffer.from("backthread-cli-auth");
+var HKDF_INFO = Buffer.from("device-token-v1");
+function generateSessionId() {
+  return toB64url(randomBytes(32));
+}
+function generateEphemeralKeypair() {
+  const ecdh = createECDH("prime256v1");
+  ecdh.generateKeys();
+  return { ecdh, publicKeyB64url: toB64url(ecdh.getPublicKey()) };
+}
+function decryptToken(enc, ecdh) {
+  const pagePub = fromB64url(enc.page_ephemeral_pubkey);
+  const shared = ecdh.computeSecret(pagePub);
+  const aesKey = Buffer.from(hkdfSync("sha256", shared, HKDF_SALT, HKDF_INFO, 32));
+  const ctFull = fromB64url(enc.ciphertext);
+  const tag = ctFull.subarray(ctFull.length - 16);
+  const ct = ctFull.subarray(0, ctFull.length - 16);
+  const iv = fromB64url(enc.iv);
+  const decipher = createDecipheriv("aes-256-gcm", aesKey, iv);
+  decipher.setAuthTag(tag);
+  return Buffer.concat([decipher.update(ct), decipher.final()]).toString("utf8");
+}
+function toB64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+function fromB64url(s) {
+  return Buffer.from(s.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+}
+// src/cliAuthPoll.ts
+var TOKEN_RE = /^backthread_pat_[A-Za-z0-9_-]+$/;
+async function pollForToken(sessionId, keypair, opts = {}) {
+  const env = opts.env ?? process.env;
+  const doFetch = opts.fetchImpl ?? fetch;
+  const interval = opts.intervalMs ?? 1500;
+  const timeout = opts.timeoutMs ?? 5 * 6e4;
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const now = opts.now ?? (() => Date.now());
+  const url2 = buildCliAuthPollUrl(env);
+  const deadline = now() + timeout;
+  while (now() < deadline) {
+    let res;
+    try {
+      res = await doFetch(url2, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", ...versionHeaders() },
+        // The CLI is the CONSUMING poller (default mode) — the browser peeks separately.
+        body: JSON.stringify({ session_id: sessionId })
+      });
+    } catch {
+      await sleep(interval);
+      continue;
+    }
+    if (res.status === 429 || res.status >= 500) {
+      await sleep(interval);
+      continue;
+    }
+    const body = await res.json().catch(() => null);
+    const status = typeof body?.status === "string" ? body.status : null;
+    if (status === "ready") {
+      const enc = extractPayload(body);
+      if (!enc) return { ok: false, reason: "error", message: "incomplete token payload from the server" };
+      let token;
+      try {
+        token = decryptToken(enc, keypair.ecdh);
+      } catch {
+        return { ok: false, reason: "error", message: "could not decrypt the token (key mismatch)" };
+      }
+      if (!TOKEN_RE.test(token)) {
+        return { ok: false, reason: "error", message: "the decrypted token was malformed" };
+      }
+      return { ok: true, token };
+    }
+    if (status === "expired") {
+      return { ok: false, reason: "expired", message: "the login session expired before you authorized" };
+    }
+    if (status === "consumed") {
+      return { ok: false, reason: "error", message: "this login was already used \u2014 start a fresh `bt login`" };
+    }
+    await sleep(interval);
+  }
+  return { ok: false, reason: "timeout", message: "timed out waiting for the browser to authorize this device" };
+}
+function extractPayload(body) {
+  if (!body) return null;
+  const { page_ephemeral_pubkey, iv, ciphertext } = body;
+  if (typeof page_ephemeral_pubkey === "string" && typeof iv === "string" && typeof ciphertext === "string") {
+    return { page_ephemeral_pubkey, iv, ciphertext };
+  }
+  return null;
+}
 // src/login.ts
 async function login(opts = {}) {
   const env = opts.env ?? process.env;
   const log = opts.log ?? ((m) => console.error(m));
   if (opts.claim) {
-    const result = await exchangeClaim(opts.claim, { env, label: deviceLabel() });
-    log(result.message);
-    return { ok: result.ok, message: result.message };
+    const result2 = await exchangeClaim(opts.claim, { env, label: deviceLabel() });
+    log(result2.message);
+    return { ok: result2.ok, message: result2.message };
   }
   if (opts.device) {
     return deviceLogin(log);
   }
-  const handle = await startLoopbackServer();
-  const authUrl = buildCliAuthUrl(handle.port, handle.state, env);
+  const sessionId = generateSessionId();
+  const keypair = generateEphemeralKeypair();
+  const authUrl = buildCliAuthUrl(sessionId, keypair.publicKeyB64url, env, deviceLabel());
   log("Opening your browser to authorize this device\u2026");
-  log(`If it doesn't open, visit:
+  log(`If it doesn't open \u2014 or you're on a remote/SSH box \u2014 open this on any device:
   ${authUrl}
 `);
@@ -7303,17 +7299,21 @@ async function login(opts = {}) {
       log("(Could not open a browser automatically \u2014 use the URL above.)");
     }
   }
-  let token;
-  try {
-    token = await handle.waitForToken();
-  } catch (err) {
-    handle.close();
-    return { ok: false, message: `Login failed: ${err.message}` };
+  const poll = opts.pollImpl ?? pollForToken;
+  const result = await poll(sessionId, keypair, { env });
+  if (!result.ok) {
+    return { ok: false, message: pollFailureMessage(result) };
   }
-  await updateConfig({ device_token: token }, env);
+  await updateConfig({ device_token: result.token }, env);
   log(`Authorized. Token stored in ${configLocationHint2(env)} (chmod 0600).`);
   return { ok: true, message: "Device authorized and token stored." };
 }
+function pollFailureMessage(result) {
+  if (result.reason === "expired" || result.reason === "timeout") {
+    return `Login ${result.reason === "expired" ? "expired" : "timed out"}: ${result.message}. Re-run \`backthread login\` to try again.`;
+  }
+  return `Login failed: ${result.message}`;
+}
 function deviceLabel() {
   try {
     const h = hostname();
@@ -7330,10 +7330,11 @@ function deviceLogin(log) {
     [
       "Headless (--device) login is not available yet.",
       "",
-      "The device-code fallback needs a server-side device-authorization endpoint",
-      "that ships in a later task. For now, run `backthread login` on a machine with a",
-      "browser, or mint a token from the web app (Account \u2192 Connected devices) and",
-      'place it in ~/.backthread/config.json under "device_token".'
+      "You usually don\u2019t need it: `backthread login` prints a URL you can open on ANY",
+      "device (phone, laptop) \u2014 the token is delivered by polling, so the browser doesn\u2019t",
+      "have to be on this machine. For a fully browserless box, mint a token from the web",
+      "app (Account \u2192 Connected devices) and place it in ~/.backthread/config.json under",
+      '"device_token", or use `--claim <code>` from the web app.'
     ].join("\n")
   );
   return { ok: false, message: "--device fallback not implemented yet." };
@@ -14533,8 +14534,8 @@ function uint8ArrayToBase64(bytes) {
   }
   return btoa(binaryString);
 }
-function base64urlToUint8Array(base64url4) {
-  const base643 = base64url4.replace(/-/g, "+").replace(/_/g, "/");
+function base64urlToUint8Array(base64url3) {
+  const base643 = base64url3.replace(/-/g, "+").replace(/_/g, "/");
   const padding = "=".repeat((4 - base643.length % 4) % 4);
   return base64ToUint8Array(base643 + padding);
 }
@@ -14791,7 +14792,7 @@ var safeDecodeAsync = /* @__PURE__ */ _safeDecodeAsync($ZodRealError);
 var regexes_exports = {};
 __export(regexes_exports, {
   base64: () => base64,
-  base64url: () => base64url2,
+  base64url: () => base64url,
   bigint: () => bigint,
   boolean: () => boolean,
   browserEmail: () => browserEmail,
@@ -14886,7 +14887,7 @@ var mac = (delimiter) => {
 var cidrv4 = /^((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\/([0-9]|[1-2][0-9]|3[0-2])$/;
 var cidrv6 = /^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|::|([0-9a-fA-F]{1,4})?::([0-9a-fA-F]{1,4}:?){0,6})\/(12[0-8]|1[01][0-9]|[1-9]?[0-9])$/;
 var base64 = /^$|^(?:[0-9a-zA-Z+/]{4})*(?:(?:[0-9a-zA-Z+/]{2}==)|(?:[0-9a-zA-Z+/]{3}=))?$/;
-var base64url2 = /^[A-Za-z0-9_-]*$/;
+var base64url = /^[A-Za-z0-9_-]*$/;
 var hostname2 = /^(?=.{1,253}\.?$)[a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?(?:\.[a-zA-Z0-9](?:[-0-9a-zA-Z]{0,61}[0-9a-zA-Z])?)*\.?$/;
 var domain = /^([a-zA-Z0-9](?:[a-zA-Z0-9-]{0,61}[a-zA-Z0-9])?\.)+[a-zA-Z]{2,}$/;
 var httpProtocol = /^https?$/;
@@ -15900,14 +15901,14 @@ var $ZodBase64 = /* @__PURE__ */ $constructor("$ZodBase64", (inst, def) => {
   };
 });
 function isValidBase64URL(data) {
-  if (!base64url2.test(data))
+  if (!base64url.test(data))
     return false;
   const base643 = data.replace(/[-_]/g, (c) => c === "-" ? "+" : "/");
   const padded = base643.padEnd(Math.ceil(base643.length / 4) * 4, "=");
   return isValidBase64(padded);
 }
 var $ZodBase64URL = /* @__PURE__ */ $constructor("$ZodBase64URL", (inst, def) => {
-  def.pattern ?? (def.pattern = base64url2);
+  def.pattern ?? (def.pattern = base64url);
   $ZodStringFormat.init(inst, def);
   inst._zod.bag.contentEncoding = "base64url";
   inst._zod.check = (payload) => {
@@ -25936,7 +25937,7 @@ __export(external_exports, {
   any: () => any,
   array: () => array,
   base64: () => base642,
-  base64url: () => base64url3,
+  base64url: () => base64url2,
   bigint: () => bigint2,
   boolean: () => boolean2,
   catch: () => _catch2,
@@ -26166,7 +26167,7 @@ __export(schemas_exports2, {
   any: () => any,
   array: () => array,
   base64: () => base642,
-  base64url: () => base64url3,
+  base64url: () => base64url2,
   bigint: () => bigint2,
   boolean: () => boolean2,
   catch: () => _catch2,
@@ -26788,7 +26789,7 @@ var ZodBase64URL = /* @__PURE__ */ $constructor("ZodBase64URL", (inst, def) => {
   $ZodBase64URL.init(inst, def);
   ZodStringFormat.init(inst, def);
 });
-function base64url3(params) {
+function base64url2(params) {
   return _base64url(ZodBase64URL, params);
 }
 var ZodE164 = /* @__PURE__ */ $constructor("ZodE164", (inst, def) => {
@@ -33696,6 +33697,8 @@ var StdioServerTransport = class {
 };
 // src/query.ts
+var DEFAULT_QUESTION = "How does this project work?";
+var GROUNDED_ASK_TIMEOUT_MS = 3e4;
 function parseSlug2(slug) {
   const parts = slug.trim().replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
   if (parts.length !== 2) return null;
@@ -33741,9 +33744,12 @@ async function queryDecisions(input, deps = {}) {
       };
     }
     const deepLink = buildRepoDeepLink(repo.owner, repo.name, env);
+    const question = typeof input.question === "string" && input.question.trim().length > 0 ? input.question.trim() : DEFAULT_QUESTION;
+    const ac = new AbortController();
+    const timer = setTimeout(() => ac.abort(), GROUNDED_ASK_TIMEOUT_MS);
     let res;
     try {
-      res = await doFetch(buildReadDecisionsUrl(env), {
+      res = await doFetch(buildGroundedAskUrl(env), {
         method: "POST",
         headers: {
           // Bearer device token — never logged.
@@ -33752,15 +33758,20 @@ async function queryDecisions(input, deps = {}) {
           ...versionHeaders()
           // x-backthread-version — server-side compat guard
         },
-        body: JSON.stringify({ repo: { owner: repo.owner, name: repo.name } })
+        // The server accepts `repo` as an "owner/name" slug (it re-resolves + gates).
+        body: JSON.stringify({ question, repo: `${repo.owner}/${repo.name}` }),
+        signal: ac.signal
       });
     } catch (e) {
+      const aborted2 = e.name === "AbortError";
       return {
         status: "read-failed",
-        detail: `read request failed: ${e.message}`,
+        detail: aborted2 ? `grounded-ask timed out after ${GROUNDED_ASK_TIMEOUT_MS / 1e3}s \u2014 try again.` : `grounded-ask request failed: ${e.message}`,
         repo,
         deepLink
       };
+    } finally {
+      clearTimeout(timer);
     }
     let payload;
     try {
@@ -33768,60 +33779,53 @@ async function queryDecisions(input, deps = {}) {
     } catch {
       payload = null;
     }
+    const rec = payload && typeof payload === "object" ? payload : {};
     if (!res.ok) {
-      const obj = payload && typeof payload === "object" ? payload : {};
-      const serverErr = typeof obj.message === "string" && obj.message.length > 0 ? obj.message : "error" in obj ? String(obj.error) : `HTTP ${res.status}`;
+      const serverErr = typeof rec.message === "string" && rec.message.length > 0 ? rec.message : "error" in rec ? String(rec.error) : `HTTP ${res.status}`;
       return {
         status: "read-failed",
-        detail: `read rejected (${res.status}): ${serverErr}`,
+        detail: `grounded-ask rejected (${res.status}): ${serverErr}`,
+        repo,
+        deepLink
+      };
+    }
+    const answer = typeof rec.answer === "string" ? rec.answer : "";
+    if (!answer) {
+      return {
+        status: "read-failed",
+        detail: "grounded-ask returned no answer.",
         repo,
         deepLink
       };
     }
-    const rec = payload && typeof payload === "object" ? payload : {};
-    const flows = normalizeFlows(rec.flows);
-    const decisions = normalizeDecisions(rec.decisions);
     const upgrade = typeof rec.upgrade === "string" && rec.upgrade.length > 0 ? rec.upgrade : void 0;
-    const base = `${flows.length} flow(s), ${decisions.length} decision(s) for ${repo.owner}/${repo.name}.`;
     return {
       status: "ok",
-      detail: base,
+      detail: `grounded answer (${typeof rec.coverage === "string" ? rec.coverage : "partial"} coverage)`,
       repo,
-      flows,
-      decisions,
-      deepLink,
+      answer,
+      coverage: typeof rec.coverage === "string" ? rec.coverage : void 0,
+      citations: normalizeCitations(rec.citations),
+      inferredSpans: Array.isArray(rec.inferredSpans) ? rec.inferredSpans.map(String) : [],
+      // Prefer the server's deepLink; fall back to the locally-built one.
+      deepLink: typeof rec.deepLink === "string" && rec.deepLink.length > 0 ? rec.deepLink : deepLink,
       ...upgrade ? { upgrade } : {}
     };
   } catch (e) {
     return { status: "error", detail: `query failed (swallowed): ${e.message}` };
   }
 }
-function normalizeFlows(raw) {
-  if (!Array.isArray(raw)) return [];
-  return raw.map((f) => {
-    const r = f && typeof f === "object" ? f : {};
-    return {
-      id: String(r.id ?? ""),
-      name: String(r.name ?? ""),
-      lifecycle: String(r.lifecycle ?? ""),
-      salience: typeof r.salience === "number" ? r.salience : null,
-      canonicalFlowId: typeof r.canonicalFlowId === "string" ? r.canonicalFlowId : null
-    };
-  });
-}
-function normalizeDecisions(raw) {
+function normalizeCitations(raw) {
   if (!Array.isArray(raw)) return [];
-  return raw.map((d) => {
-    const r = d && typeof d === "object" ? d : {};
+  return raw.map((c) => {
+    const r = c && typeof c === "object" ? c : {};
     return {
-      id: String(r.id ?? ""),
+      n: typeof r.n === "number" ? r.n : 0,
+      decisionId: String(r.decisionId ?? ""),
       title: String(r.title ?? ""),
-      why: typeof r.why === "string" ? r.why : null,
-      significance: typeof r.significance === "number" ? r.significance : null,
-      domainRisk: typeof r.domainRisk === "string" ? r.domainRisk : null,
-      decidedAt: typeof r.decidedAt === "string" ? r.decidedAt : null,
-      flowIds: Array.isArray(r.flowIds) ? r.flowIds.map(String) : [],
-      moduleIds: Array.isArray(r.moduleIds) ? r.moduleIds.map(String) : []
+      url: String(r.url ?? ""),
+      moduleIds: Array.isArray(r.moduleIds) ? r.moduleIds.map(String) : [],
+      decidedAt: typeof r.decidedAt === "string" ? r.decidedAt : null
     };
   });
 }
@@ -33857,7 +33861,7 @@ function isFailure(o) {
 async function handleQueryTool(args = {}, deps = {}) {
   const run = deps.queryDecisionsImpl ?? queryDecisions;
   try {
-    const outcome = await run({ repo: args.repo, cwd: args.cwd }, deps.queryDeps);
+    const outcome = await run({ question: args.question, repo: args.repo, cwd: args.cwd }, deps.queryDeps);
     let text = formatQueryOutcome(outcome, args.question);
     const nudge = await (deps.upgradeNudgeImpl ?? maybeUpgradeNudge)(outcome.upgrade);
     if (nudge) text += `
@@ -33868,42 +33872,11 @@ ${nudge}`;
     return textResult(`query: error \u2014 ${e.message}`, true);
   }
 }
-function formatQueryOutcome(outcome, question) {
-  if (outcome.status !== "ok") {
+function formatQueryOutcome(outcome, _question) {
+  if (outcome.status !== "ok" || !outcome.answer) {
     return `query: ${outcome.status} \u2014 ${outcome.detail}`;
   }
-  const lines = [];
-  const q = question && question.trim().length > 0 ? ` for "${question.trim()}"` : "";
-  const repoSlug = outcome.repo ? `${outcome.repo.owner}/${outcome.repo.name}` : "this repo";
-  lines.push(`How ${repoSlug} works${q} \u2014 salience-ranked from the decision log:`);
-  lines.push("");
-  const flows = outcome.flows ?? [];
-  if (flows.length > 0) {
-    lines.push("Flows (most salient first):");
-    for (const f of flows) {
-      const sal = f.salience != null ? ` [salience ${f.salience}]` : "";
-      lines.push(`  - ${f.name} (${f.lifecycle})${sal}`);
-    }
-  } else {
-    lines.push("Flows: none recorded yet.");
-  }
-  lines.push("");
-  const decisions = outcome.decisions ?? [];
-  if (decisions.length > 0) {
-    lines.push('Decisions (the "why", most significant first):');
-    for (const d of decisions) {
-      const risk = d.domainRisk ? ` {${d.domainRisk}-risk}` : "";
-      lines.push(`  - ${d.title}${risk}`);
-      if (d.why) lines.push(`      why: ${d.why}`);
-    }
-  } else {
-    lines.push("Decisions: none recorded yet.");
-  }
-  lines.push("");
-  if (outcome.deepLink) {
-    lines.push(`Open the "How it works" diagram: ${outcome.deepLink}`);
-  }
-  return lines.join("\n");
+  return outcome.answer;
 }
 function buildMcpServer(deps = {}) {
   const server = new McpServer({
@@ -33928,10 +33901,10 @@ function buildMcpServer(deps = {}) {
   server.registerTool(
     "query",
     {
-      title: "How does X work?",
-      description: 'Answer "how does X work?" for the current repo: returns the salience-ranked Flows and Decisions (the "why" layer) from your Backthread decision log, plus a deep-link into the web-app "How it works" diagram. Read-only.',
+      title: "How does it work? (grounded answer from this repo's decision log)",
+      description: `Call this FIRST whenever the user asks how or why any part of THIS repository works, is built, or was decided \u2014 before reading source files or guessing. It returns a short, grounded, CITED answer synthesized from the repo's Backthread decision log (the captured "why" that the code itself does not contain): the real reasons, trade-offs, and superseded approaches behind the current design. Pass the user's question. The answer is ready to relay verbatim \u2014 it already cites its sources and flags anything inferred. Read-only; nothing leaves the machine but the question.`,
       inputSchema: {
-        question: external_exports.string().optional().describe('The "how does X work?" question (the agent narrates the answer against the returned log).'),
+        question: external_exports.string().optional().describe(`The user's "how/why does X work?" question, in their words. Load-bearing: the server retrieves and synthesizes the answer against it.`),
         repo: external_exports.string().optional().describe('Optional repo override as "owner/name"; otherwise the configured repo or the cwd git remote.'),
         cwd: external_exports.string().optional().describe("The session's working directory (repo fallback).")
       }
@@ -33947,6 +33920,87 @@ async function startMcpServer(deps = {}) {
   return server;
 }
+// src/routingStats.ts
+import { join as join12 } from "node:path";
+import { readFile as readFile11, writeFile as writeFile9, mkdir as mkdir9, chmod as chmod8 } from "node:fs/promises";
+var STATS_FILE = "routing-stats.json";
+function statsPath(env) {
+  return join12(configDir(env), STATS_FILE);
+}
+async function readRoutingStats(deps = {}) {
+  const env = deps.env ?? process.env;
+  const read = deps.readFileImpl ?? readFile11;
+  try {
+    const raw = await read(statsPath(env), "utf8");
+    const obj = JSON.parse(raw);
+    return {
+      injected: typeof obj.injected === "number" && obj.injected >= 0 ? Math.floor(obj.injected) : 0,
+      lastInjectedAt: typeof obj.lastInjectedAt === "string" ? obj.lastInjectedAt : void 0
+    };
+  } catch {
+    return { injected: 0 };
+  }
+}
+async function recordRoutingInjected(deps = {}) {
+  const env = deps.env ?? process.env;
+  const now = deps.now ?? (() => /* @__PURE__ */ new Date());
+  const write = deps.writeFileImpl ?? writeFile9;
+  const mkdirp = deps.mkdirImpl ?? mkdir9;
+  const chmodp = deps.chmodImpl ?? chmod8;
+  try {
+    const prev = await readRoutingStats(deps);
+    const next = { injected: prev.injected + 1, lastInjectedAt: now().toISOString() };
+    await mkdirp(configDir(env), { recursive: true, mode: DIR_MODE });
+    await write(statsPath(env), `${JSON.stringify(next, null, 2)}
+`, { mode: CONFIG_MODE });
+    await chmodp(statsPath(env), CONFIG_MODE).catch(() => {
+    });
+  } catch {
+  }
+}
+// src/sessionStart.ts
+var ROUTING_CONTEXT = [
+  'This repository is set up with Backthread, which has captured the "why" behind its',
+  "changes into a decision log. The backthread `query` MCP tool (and the",
+  '`/backthread:how` slash command) answer "how does X work?" and "why was Y decided?"',
+  "with a short, CITED answer synthesized from that log \u2014 the real reasons, trade-offs,",
+  "and superseded approaches the source code itself does not contain.",
+  "",
+  "When the user asks how or why any part of THIS codebase works, is structured, or was",
+  "decided, call the backthread `query` tool FIRST \u2014 before grepping or reading source",
+  "files. Pass the user's question and relay the cited answer it returns; only read",
+  "source afterwards if it didn't cover what you need."
+].join("\n");
+function buildSessionStartOutput(isSetUp) {
+  if (!isSetUp) return {};
+  return {
+    hookSpecificOutput: {
+      hookEventName: "SessionStart",
+      additionalContext: ROUTING_CONTEXT
+    }
+  };
+}
+async function runSessionStart(deps = {}) {
+  const readConfig2 = deps.readConfig ?? readConfig;
+  const record2 = deps.recordRoutingInjected ?? recordRoutingInjected;
+  let isSetUp = false;
+  try {
+    const cfg = await readConfig2();
+    isSetUp = !!cfg.device_token;
+  } catch {
+    isSetUp = false;
+  }
+  const output = buildSessionStartOutput(isSetUp);
+  if (output.hookSpecificOutput) {
+    try {
+      await record2();
+    } catch {
+    }
+  }
+  return output;
+}
 // src/bin/backthread.ts
 var USAGE = `backthread \u2014 capture the "why" of your AI-coded changes
@@ -33963,6 +34017,9 @@ Usage:
                           (no browser needed \u2014 codes expire in ~10 minutes)
   backthread login --device     Headless / SSH login (device-code flow \u2014 coming soon)
   backthread whoami             Show the current device's config (token is never printed)
+  backthread how <question>     Ask how/why something in this repo works \u2014 prints a
+                          grounded, cited answer from your Backthread decision log
+                          (backs the /backthread:how slash command). [--cwd <path>]
   backthread capture            Capture this session's decisions (run by the SessionEnd/Stop hook)
   backthread capture --from-hook
                           Shared multi-agent hook entrypoint: read the hook payload off
@@ -33997,6 +34054,12 @@ function flagValue(rest, flag) {
   if (!value || value.startsWith("--")) return void 0;
   return value;
 }
+function stripFlag(rest, flag) {
+  const i = rest.indexOf(flag);
+  if (i === -1) return rest;
+  const dropValue = rest[i + 1] !== void 0 && !rest[i + 1].startsWith("--");
+  return [...rest.slice(0, i), ...rest.slice(i + (dropValue ? 2 : 1))];
+}
 async function runOnboarding(rest) {
   const claim = parseClaimFlag(rest);
   const result = await runStart({
@@ -34060,6 +34123,14 @@ async function main(argv, deps = {}) {
       }
       return 0;
     }
+    case "session-start": {
+      const ssAgent = parseAgent(flagValue(rest, "--agent"));
+      setRequestAgent(ssAgent === "unknown" ? "claude-code" : ssAgent);
+      await readRawHookInput().catch(() => "");
+      const output = await runSessionStart();
+      console.log(JSON.stringify(output));
+      return 0;
+    }
     case "mcp": {
       await startMcpServer();
       return null;
@@ -34083,6 +34154,15 @@ async function main(argv, deps = {}) {
       });
       return result.exitCode;
     }
+    case "how":
+    case "ask": {
+      const query = deps.queryDecisionsImpl ?? queryDecisions;
+      const cwd = flagValue(rest, "--cwd") ?? process.cwd();
+      const question = stripFlag(rest, "--cwd").join(" ").trim();
+      const outcome = await query({ question, cwd });
+      console.log(formatQueryOutcome(outcome, question));
+      return outcome.status === "ok" ? 0 : 1;
+    }
     case void 0:
       return onboarding(rest);
     case "help":
@@ -34126,5 +34206,6 @@ if (isEntryPoint()) {
 }
 export {
   main,
-  runOnboarding
+  runOnboarding,
+  stripFlag
 };

package/hooks/hooks.json CHANGED Viewed

@@ -1,6 +1,17 @@
 {
   "$comment": "The SessionEnd capture hook, declared in the PLUGIN MANIFEST (referenced from .claude-plugin/plugin.json). When Backthread is installed as a Claude Code plugin, this registers the hook automatically AT USER/GLOBAL SCOPE — no mutation of the user's project .claude/settings.json, and it fires across EVERY repo AND git worktree (ARP-680: a per-project, gitignored .claude/settings.json hook is exactly what froze the dogfood log — worktree sessions never carried it; an installed plugin's hooks follow the user, not the cwd). The command invokes the plugin's BUNDLED, self-contained bin via ${CLAUDE_PLUGIN_ROOT} (ARP-474's dist-bundle/backthread.js — committed to git so the marketplace-cloned plugin has it; CC runs no build step on install), NOT `npx backthread`, which would resolve a possibly-stale or absent global / npm-linked install (the second half of the ARP-680 dogfood freeze). The detached worker re-spawns via process.execPath + process.argv[1], so pointing argv[1] at the bundle propagates the same self-contained bin through the WHOLE chain (hook → detached worker). It routes through the shared `--from-hook` entrypoint with `--detach`: it reads the SessionEnd payload off stdin, then re-spawns a DETACHED worker that does the slow LOCALLY-redacted redact→infer→persist round-trip and returns immediately — so a ≥30s inference can't be SIGTERM'd by CC's SessionEnd hook timeout (or reaped on session exit). Best-effort, never blocks/delays the session, always exits 0 (ARP-682). `--agent claude-code` selects the CC payload shape. Mirrored by the USER-SCOPE ~/.claude/settings.json fallback that `backthread install` writes for the bare-npx (non-plugin) path (ARP-503). We register ONLY SessionEnd (once per session) on purpose — `runCapture` also handles a Stop payload, but Stop fires on every turn-end, which would capture far too aggressively, so Stop is intentionally NOT registered here.",
+  "$comment_sessionstart": "The SessionStart AMBIENT-ROUTING hook (ARP-763). Injects a one-time instruction into the session context telling Claude Code to call the `query` MCP tool FIRST on how/why-does-X questions, before grepping — so a plain 'how does X work?' routes to a grounded, cited answer with no new user habit. SYNCHRONOUS, NOT --detach: CC reads this command's STDOUT for hookSpecificOutput.additionalContext, so the bundle must print it (a detached re-spawn would print an ack instead). It does only a FAST LOCAL config read (no network), gates on a present device token (only routes when `query` can actually answer), and always exits 0 with valid JSON. PLUGIN-ONLY: runs the shipped self-contained bundle (fast, offline); the bare-npx settings.json fallback deliberately does NOT register it, because a synchronous `npx backthread session-start` would block every session start on npm's resolve (the capture hook only gets away with @latest because it's --detach'ed). npx-fallback users keep the `query` tool's imperative description.",
   "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/dist-bundle/backthread.js\" session-start --agent claude-code"
+          }
+        ]
+      }
+    ],
     "SessionEnd": [
       {
         "hooks": [

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "backthread",
-  "version": "0.5.1",
+  "version": "0.7.0",
   "description": "Backthread helps you understand your codebase while AI ships features. The CLI captures the why behind every AI session and lets you ask how your codebase works, right from the terminal.",
   "license": "MIT",
   "author": "Backthread",