backthread 0.5.1 → 0.6.0

package/.claude-plugin/plugin.json

@@ -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.6.0",
   "author": {
     "name": "Backthread"
   },
   "homepage": "https://backthread.dev",
-  "hooks": "./hooks/hooks.json",
   "mcpServers": {
     "backthread": {
       "command": "node",

package/commands/how.md

@@ -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

@@ -7017,6 +7017,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,9 +7029,6 @@ 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();
 }
@@ -33696,6 +33696,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 +33743,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 +33757,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 +33778,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) {
+function normalizeCitations(raw) {
   if (!Array.isArray(raw)) return [];
-  return raw.map((f) => {
-    const r = f && typeof f === "object" ? f : {};
+  return raw.map((c) => {
+    const r = c && typeof c === "object" ? c : {};
     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) {
-  if (!Array.isArray(raw)) return [];
-  return raw.map((d) => {
-    const r = d && typeof d === "object" ? d : {};
-    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 +33860,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 +33871,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 +33900,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 +33919,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 +34016,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 +34053,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 +34122,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 +34153,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 +34205,6 @@ if (isEntryPoint()) {
 }
 export {
   main,
-  runOnboarding
+  runOnboarding,
+  stripFlag
 };

package/hooks/hooks.json

@@ -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

@@ -1,6 +1,6 @@
 {
   "name": "backthread",
-  "version": "0.5.1",
+  "version": "0.6.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",