@davesheffer/hunch 0.4.0 → 0.8.0

package/README.md

@@ -56,13 +56,21 @@ Either way you then type `hunch …`. From a source checkout without `npm link`,
 `node dist/cli/index.js …` (or `npm run hunch -- …` to run via tsx). The rest of this
 README uses `hunch` for brevity.
 
-### 2. (Recommended) make the `claude` CLI available
+### 2. (Recommended) make a coding-assistant CLI available
 
-Hunch's LLM synthesis is billed to your **Claude Pro/Max subscription** through the
-`claude` CLI — **never** the pay-per-token API. If `claude --version` works in your
-terminal, you get full LLM-quality capture for free. If it doesn't, Hunch still works
-using a deterministic structural heuristic (lower-confidence drafts). `hunch doctor`
-tells you which mode you're in.
+Hunch's LLM synthesis is billed to **your subscription** through a coding-assistant
+CLI — **never** a pay-per-token API key (the API key is stripped from the child env).
+Hunch auto-detects the first one present, in this order:
+
+| CLI | Subscription | Detected by |
+|---|---|---|
+| `claude` (Claude Code) | Claude Pro/Max | `claude --version` |
+| `codex` (OpenAI Codex) | ChatGPT Plus/Pro | `codex --version` |
+| `cursor-agent` (Cursor) | Cursor | `cursor-agent --version` |
+
+If none is installed, Hunch still works using a deterministic structural heuristic
+(lower-confidence drafts). `hunch doctor` tells you which mode you're in; force one
+with `HUNCH_SYNTH_PROVIDER=claude-cli|codex-cli|cursor-agent|deterministic`.
 
 ### 3. Initialize the repo you want a memory for
 
@@ -98,18 +106,38 @@ normally and Claude consults Hunch, or invoke the slash commands:
 | `/hunch-fragile` | a fragility report (the riskiest code, with evidence) |
 
 The MCP tools Claude calls under the hood: `hunch_why`, `hunch_query`,
-`hunch_check_constraints`, `hunch_get_dependents` (blast radius), `hunch_bug_lineage`,
+`hunch_check_constraints`, `hunch_get_dependents` (blast radius), `hunch_blast_radius`
+(dependent files + near-violations a change could break indirectly), `hunch_bug_lineage`,
 `hunch_context` (surgical minimal slice for a task), `hunch_record_decision` (write-back).
 
+### Works with any MCP assistant
+
+The Hunch MCP server is **client-agnostic** — one `.hunch/` graph powers every
+assistant. `hunch init` scaffolds each tool's MCP config + ambient grounding so
+they all consult the same memory:
+
+| Assistant | MCP config | Grounding file |
+|---|---|---|
+| Claude Code | `.mcp.json` | `CLAUDE.md` + `/hunch-*` slash commands |
+| Cursor | `.cursor/mcp.json` | `.cursor/rules/hunch.mdc` (always-applied) |
+| VS Code (Copilot) | `.vscode/mcp.json` | `.github/copilot-instructions.md` |
+| Codex CLI | `.codex/config.toml` | `AGENTS.md` |
+| Anything else | — | `AGENTS.md` (cross-tool standard) |
+
+Each writer **merges** into existing files (other MCP servers and your own prose are
+preserved) and is idempotent. Opt out with `hunch init --no-providers`.
+
 **Through the CLI** — the same graph, from your terminal:
 
 | Command | What |
 |---|---|
-| `hunch init [--enforce]` | scaffold `.hunch/`, index, install hook + merge driver, wire up Claude Code (`--enforce` adds a pre-commit invariant guard) |
+| `hunch init` | scaffold `.hunch/`, index, install hook + merge driver, auto-install the advisory pre-commit guard, install the **Claude Code agent hooks**, and wire up **every assistant** (Claude Code, Cursor, VS Code/Copilot, Codex, AGENTS.md). Flags: `--no-enforce`, `--enforce-strict`, `--no-providers`, `--no-agent-hooks`, `--firmness <level>` |
 | `hunch index` | parse repo → symbols / edges / components (deterministic, no LLM) |
 | `hunch backfill --since 90d` | replay git history → seed decisions |
 | `hunch sync [sha]` | turn a commit into a Decision (run automatically by the hook) |
 | `hunch record-bug --test <id> --message <m>` | capture a Bug from a failing test |
+| `hunch record-constraint "<statement>" [--scope <globs>] [--severity advisory\|warning\|blocking] [--type …] [--rationale <t>] [--source-decision <id>]` | record an invariant the code must not break (what `hunch check` + the strict agent hook enforce) |
+| `hunch firmness [off\|advisory\|firm\|strict]` | get/set how firmly the agent hook enforces Hunch before edits (no arg prints the current level) |
 | `hunch test [cmd…]` | run the suite (default `npm test`); auto-capture failures as Bugs (suspects + recurrence→Constraints), mark passing tests' bugs fixed |
 | `hunch why <path\|symbol>` | decisions / bugs / constraints explaining a target (flags `⚠STALE`) |
 | `hunch query "<q>" [--semantic]` | full-text + graph search (`--semantic` blends in local embeddings) |
@@ -124,6 +152,37 @@ The MCP tools Claude calls under the hood: `hunch_why`, `hunch_query`,
 | `hunch doctor` | environment diagnostics (git, auth mode, schema version, counts) |
 | `hunch mcp` | start the MCP server over stdio (Claude Code connects here) |
 
+## Grounding the agent automatically (firmness)
+
+Telling an assistant "consult Hunch first" in a prompt is advisory — it drifts. `hunch
+init` instead installs two **Claude Code agent hooks** (in `.claude/settings.json`) so the
+grounding is enforced by the harness, not by the model's memory:
+
+- **Before every edit** (`PreToolUse` on `Edit`/`Write`/`MultiEdit`) Hunch injects the
+  relevant slice for the file being touched — its decisions, invariants, bug history, and
+  blast radius — straight into the model's context.
+- **On every prompt** (`UserPromptSubmit`) it reminds the agent to query Hunch.
+
+How hard it pushes is one committed knob — set it once, it applies to the whole team:
+
+```bash
+hunch firmness            # print the current level
+hunch firmness strict     # change it (takes effect on the next edit; no restart)
+```
+
+| Level | Before an edit |
+|---|---|
+| `off` | nothing (hook is a no-op) |
+| `advisory` *(default)* | inject the relevant Hunch slice as context |
+| `firm` | advisory **+** explicitly flag invariants in the file's scope |
+| `strict` | firm **+** **deny** an edit that hits a *blocking* invariant (directly or via blast radius), feeding the invariant back as the refusal reason |
+
+The hook never breaks your flow: any error or unrecognized input emits nothing and exits
+0, and it stays silent on files Hunch hasn't learned yet. `strict` only bites once you have
+**blocking** constraints recorded (`hunch record-constraint … --severity blocking`) — with
+none, every level degrades to context-only. Opt out of the hooks entirely with `hunch init
+--no-agent-hooks`.
+
 ## Semantic search (optional)
 
 By default `hunch query` and the `hunch_query` MCP tool use fast keyword (FTS) search —

package/dist/cli/index.js

@@ -15,6 +15,7 @@
  */
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
+import { relative } from "node:path";
 import { Command } from "commander";
 import { hunchPaths, findRoot } from "../core/paths.js";
 import { HunchStore } from "../store/hunchStore.js";
@@ -27,8 +28,12 @@ import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, commitFiles
 import { installPostCommitHook, installPreCommitHook } from "../integrations/hooks.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { updateClaudeMd } from "../integrations/claudemd.js";
-import { writeMcpJson, writeSlashCommands } from "../integrations/scaffold.js";
+import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
+import { scaffoldProviders } from "../integrations/providers.js";
 import { formatContext } from "../core/format.js";
+import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
+import { blockingInScope } from "../core/hookpolicy.js";
+import { constraintId } from "../core/ids.js";
 import { readManifest, writeManifest, SCHEMA_VERSION } from "../core/migrate.js";
 import { mergeHunchJson } from "../store/merge.js";
 import { planCompaction } from "../store/compact.js";
@@ -47,9 +52,17 @@ program
     .command("init")
     .description("Scaffold .hunch/, index the repo, install the git hook, and wire up Claude Code.")
     .option("--no-index", "skip the initial repo index")
-    .option("--enforce", "install an advisory pre-commit constraint guard")
-    .option("--enforce-strict", "install a pre-commit guard that FAILS the commit on a blocking invariant")
+    .option("--no-enforce", "do not install the advisory pre-commit constraint guard")
+    .option("--enforce-strict", "make the pre-commit guard FAIL the commit on a blocking invariant (direct or near)")
+    .option("--no-providers", "skip scaffolding non-Claude assistant configs (Cursor / VS Code / Codex / AGENTS.md)")
+    .option("--no-agent-hooks", "skip installing the Claude Code agent hooks (.claude/settings.json)")
+    .option("--firmness <level>", "agent-hook firmness: off | advisory | firm | strict")
     .action((opts) => {
+    // Validate --firmness up front, before any side effects (indexing, git hooks,
+    // .mcp.json) or opening the store — a bad value must not leave a half-init.
+    if (opts.firmness !== undefined && !isFirmness(opts.firmness)) {
+        return fail(`--firmness must be one of: ${FIRMNESS_LEVELS.join(", ")}`);
+    }
     const root = findRoot();
     const paths = hunchPaths(root);
     const store = new HunchStore(paths);
@@ -70,9 +83,13 @@ program
         console.log(`  ✓ post-commit hook ${h.action} (learning loop)`);
         const m = installMergeDriver(root, inv.shell);
         console.log(`  ✓ team merge driver ${m.action}`);
-        if (opts.enforce || opts.enforceStrict) {
-            const p = installPreCommitHook(root, inv.shell, !!opts.enforceStrict);
-            console.log(`  ✓ pre-commit constraint guard ${p.action} (${opts.enforceStrict ? "strict — blocks on blocking invariants" : "advisory"})`);
+        // Auto-install the pre-commit guard by default (advisory: flags invariants
+        // touched directly OR via blast radius, never blocks). Opt out with
+        // --no-enforce; --enforce-strict makes blocking near/direct hits fail the commit.
+        if (opts.enforce !== false || opts.enforceStrict) {
+            const strict = !!opts.enforceStrict;
+            const p = installPreCommitHook(root, inv.shell, strict);
+            console.log(`  ✓ pre-commit constraint guard ${p.action} (${strict ? "strict — blocks on blocking invariants, direct or near" : "advisory — flags invariants in scope or blast radius"})`);
         }
     }
     else {
@@ -84,6 +101,26 @@ program
     console.log(`  ✓ wrote ${cmds.length} slash commands (/hunch-why, /hunch-fix, /hunch-fragile)`);
     const cmd = updateClaudeMd(root, store);
     console.log(`  ✓ updated ${rel(root, cmd)} with ambient Hunch context`);
+    // Firmness: stamp .hunch/config.json (default advisory) so `hunch hook` reads a
+    // level even before the user runs `hunch firmness` (--firmness validated above).
+    const firmness = writeConfig(paths, opts.firmness ? { firmness: opts.firmness } : {}).firmness;
+    // Agent hooks: ground the assistant in Hunch automatically (PreToolUse injects
+    // context before edits; UserPromptSubmit reminds). Reads firmness at run time.
+    if (opts.agentHooks !== false) {
+        const a = installClaudeHooks(root, `${inv.shell} hook`);
+        console.log(`  ✓ Claude Code agent hooks ${a.action} (firmness: ${firmness} — change with \`hunch firmness <level>\`)`);
+    }
+    // Multi-assistant compatibility: the MCP server is client-agnostic, so wire up
+    // Cursor / VS Code (Copilot) / Codex / AGENTS.md to the same .hunch/ graph.
+    if (opts.providers !== false) {
+        const ps = scaffoldProviders(root, inv.mcp, store);
+        const ok = ps.filter((p) => !p.error);
+        const total = ok.reduce((a, p) => a + p.files.length, 0);
+        console.log(`  ✓ wrote ${total} multi-assistant config file(s) → ${ok.map((p) => p.assistant).join(", ")}`);
+        for (const p of ps)
+            if (p.error)
+                console.log(`  ⚠ skipped ${p.assistant}: ${p.error}`);
+    }
     store.close();
     console.log("\nNext: make a commit (the hook captures a decision), then ask Claude Code \"why is X built this way?\"");
     console.log("Cold start? Seed from history:  hunch backfill --since 90d");
@@ -320,6 +357,41 @@ program
         console.log(`  ↳ promoted constraint ${r.constraint.id} [${r.constraint.severity}]: ${r.constraint.statement}`);
     store.close();
 });
+// ---- record-constraint (human-authored invariant) -------------------------
+program
+    .command("record-constraint")
+    .description("Record an invariant the codebase must not break — what `hunch check` and the strict agent hook enforce.")
+    .argument("<statement>", 'the invariant, e.g. "vectors are derived, never the source of truth"')
+    .option("--scope <globs>", "comma-separated path/glob(s) it applies to (e.g. src/store/**)", "")
+    .option("--severity <s>", "advisory | warning | blocking", "warning")
+    .option("--type <t>", "security | performance | correctness | architecture | compliance", "correctness")
+    .option("--rationale <text>", "why it must hold", "")
+    .option("--source-decision <id>", "decision id this derives from")
+    .option("--enforcement <e>", "advisory_v1 | ci | manual", "advisory_v1")
+    .action((statement, opts) => {
+    const SEV = ["advisory", "warning", "blocking"];
+    if (!SEV.includes(opts.severity))
+        return fail(`--severity must be one of: ${SEV.join(", ")}`);
+    const { store, root } = storeFor();
+    store.json.ensureDirs();
+    const scope = opts.scope.split(",").map((s) => s.trim()).filter(Boolean);
+    const c = store.json.put("constraints", {
+        id: constraintId(statement),
+        type: opts.type,
+        statement,
+        scope,
+        severity: opts.severity,
+        enforcement: opts.enforcement,
+        rationale: opts.rationale,
+        source_decision: opts.sourceDecision ?? null,
+        violations: [],
+        provenance: { source: "human_confirmed", confidence: 1, evidence: [], last_verified: new Date().toISOString() },
+    });
+    store.reindex();
+    updateClaudeMd(root, store);
+    console.log(`✓ recorded ${c.severity} constraint ${c.id}: "${c.statement}" (scope: ${scope.join(", ") || "repo"})`);
+    store.close();
+});
 // ---- test (failure-learning loop) -----------------------------------------
 program
     .command("test")
@@ -518,6 +590,87 @@ program
     process.stdout.write(formatContext(store.assembleContext(target, Number(opts.budget))));
     store.close();
 });
+// ---- firmness (agent-hook enforcement level) ------------------------------
+program
+    .command("firmness")
+    .description("Get or set how firmly the Claude Code agent hook enforces Hunch before edits.")
+    .argument("[level]", "off | advisory | firm | strict (omit to print the current level)")
+    .action((level) => {
+    const paths = hunchPaths(findRoot());
+    if (!level) {
+        console.log(`firmness: ${readConfig(paths).firmness}`);
+        console.log(`levels:   ${FIRMNESS_LEVELS.join(" | ")}  (set with: hunch firmness <level>)`);
+        return;
+    }
+    if (!isFirmness(level)) {
+        return fail(`firmness must be one of: ${FIRMNESS_LEVELS.join(", ")}`);
+    }
+    const next = writeConfig(paths, { firmness: level }).firmness;
+    console.log(`✓ firmness set to ${next} (takes effect on the next edit — no Claude Code restart needed).`);
+});
+// ---- hook (Claude Code agent-hook handler) --------------------------------
+program
+    .command("hook")
+    .description("Claude Code hook handler: inject relevant Hunch context before edits (and, at strict firmness, deny edits that hit a blocking invariant). Reads the hook event JSON on stdin.")
+    .action(async () => {
+    // A hook MUST NEVER break the agent: on ANY error or unrecognized input we
+    // emit nothing and exit 0 (the action defers to Claude Code's normal flow).
+    let store = null;
+    try {
+        const evt = JSON.parse(await readStdin());
+        const root = findRoot();
+        const paths = hunchPaths(root);
+        const firmness = readConfig(paths).firmness;
+        if (firmness === "off")
+            return;
+        if (evt.hook_event_name === "UserPromptSubmit") {
+            emitContext("UserPromptSubmit", HOOK_REMINDER);
+            return;
+        }
+        if (evt.hook_event_name !== "PreToolUse")
+            return;
+        const abs = evt.tool_input?.file_path;
+        if (!abs)
+            return;
+        const target = toRepoRel(root, abs);
+        // Outside the repo (".." prefix) or on another drive (absolute, e.g. "D:/…")
+        // → nothing for Hunch to say.
+        if (!target || target.startsWith("..") || /^[a-zA-Z]:/.test(target))
+            return;
+        store = new HunchStore(paths);
+        // strict: refuse an edit that hits a BLOCKING invariant (direct OR via blast
+        // radius), feeding the invariant statement back as the refusal reason. Reindex
+        // first so the blast radius reflects uncommitted edges — strict opts into the
+        // cost for correctness. Advisory/firm skip it: the hook fires on every edit,
+        // and decisions/constraints don't change between commits, so the committed
+        // index is good enough for grounding.
+        if (firmness === "strict") {
+            store.reindex();
+            const deny = blockingInScope(store, target);
+            if (deny) {
+                emitDeny(deny.reason);
+                return;
+            }
+        }
+        // advisory / firm / strict(non-blocking): inject the relevant Hunch slice.
+        const ctx = store.assembleContext(target);
+        const hasContent = ctx.constraints.length || ctx.decisions.length || ctx.bugs.length || ctx.blast_radius.length;
+        if (!hasContent)
+            return; // no noise on files Hunch hasn't learned yet
+        let text = formatContext(ctx).trim();
+        if (firmness !== "advisory" && ctx.constraints.length) {
+            const names = ctx.constraints.map((c) => `[${c.severity}] ${c.statement}`).join("; ");
+            text += `\n\n⚠ This file is in scope of ${ctx.constraints.length} invariant(s): ${names}. Preserve them.`;
+        }
+        emitContext("PreToolUse", text);
+    }
+    catch {
+        // swallow — never block an edit on a hook failure
+    }
+    finally {
+        store?.close();
+    }
+});
 // ---- review (curate loop) -------------------------------------------------
 program
     .command("review")
@@ -672,16 +825,22 @@ program
     console.log(`schema:     v${onDisk} (hunch v${SCHEMA_VERSION})${schemaNote}`);
     const provider = await selectProvider();
     console.log(`synthesis:  ${provider.name}`);
-    // Synthesis is billed to the user's Claude SUBSCRIPTION via the `claude` CLI,
-    // never the pay-per-token API. Surface whatever stands between here and that.
-    if (provider.name === "claude-cli") {
-        const hadKey = !!(process.env.ANTHROPIC_API_KEY || process.env.ANTHROPIC_AUTH_TOKEN);
-        console.log(`            ↳ LLM synthesis billed to your Claude subscription` +
-            (hadKey ? ` (ANTHROPIC_API_KEY in env is stripped — never billed to the API)` : ``));
+    // Synthesis is billed to the user's SUBSCRIPTION via a coding-assistant CLI,
+    // never a pay-per-token API key. Surface which one — or what's missing.
+    const SUB = {
+        "claude-cli": { label: "Claude subscription (claude CLI)", strip: "ANTHROPIC_API_KEY" },
+        "codex-cli": { label: "ChatGPT subscription (codex CLI)", strip: "OPENAI_API_KEY" },
+        "cursor-agent": { label: "Cursor subscription (cursor-agent CLI)" },
+    };
+    const sub = SUB[provider.name];
+    if (sub) {
+        const hadKey = sub.strip && !!process.env[sub.strip];
+        console.log(`            ↳ LLM synthesis billed to your ${sub.label}` +
+            (hadKey ? ` (${sub.strip} in env is stripped — never billed to the API)` : ``));
     }
-    else if (provider.name === "deterministic") {
-        console.log(dim(`            ↳ no \`claude\` CLI — synthesis uses the offline heuristic (advisory, low-confidence)`));
-        console.log(dim(`              for full synthesis: install Claude Code + \`claude /login\`, or set CLAUDE_CODE_OAUTH_TOKEN (\`claude setup-token\`) for CI`));
+    else {
+        console.log(dim(`            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence)`));
+        console.log(dim(`              for full synthesis install one: Claude Code (\`claude /login\`), Codex (\`codex login\`), or Cursor (\`cursor-agent login\`)`));
     }
     const c = store.reindex().counts;
     console.log(`hunch:      ${c.symbols} symbols, ${c.edges} edges, ${c.components} components, ${c.decisions} decisions, ${c.bugs} bugs, ${c.constraints} constraints`);
@@ -708,6 +867,37 @@ function fail(msg) {
     console.error(`error: ${msg}`);
     process.exitCode = 1;
 }
+// --- agent-hook helpers (used by `hunch hook`) -----------------------------
+const HOOK_REMINDER = "Hunch (engineering memory) is available for this repo. Before editing, call " +
+    "hunch_check_constraints(scope) for do-not-break invariants and hunch_why(target) " +
+    "for the rationale; use hunch_get_dependents for blast radius and hunch_bug_lineage " +
+    "for prior root causes. After a non-trivial choice, record it with hunch_record_decision.";
+/** Read all of stdin (the hook event JSON). A TTY (no piped input) resolves to ""
+ *  so an accidental interactive `hunch hook` exits cleanly instead of hanging. */
+function readStdin() {
+    return new Promise((resolve) => {
+        if (process.stdin.isTTY)
+            return resolve("");
+        let data = "";
+        process.stdin.setEncoding("utf8");
+        process.stdin.on("data", (c) => (data += c));
+        process.stdin.on("end", () => resolve(data));
+        process.stdin.on("error", () => resolve(data));
+    });
+}
+/** Absolute edit path → repo-relative, forward-slash (constraint scopes are
+ *  forward-slash globs even on Windows). */
+function toRepoRel(root, abs) {
+    return relative(root, abs).split("\\").join("/");
+}
+function emitContext(event, text) {
+    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } }));
+}
+function emitDeny(reason) {
+    process.stdout.write(JSON.stringify({
+        hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason },
+    }));
+}
 program.parseAsync().catch((e) => {
     try {
         openStore?.close();

package/dist/core/config.js

@@ -0,0 +1,35 @@
+/** Hunch user config (`.hunch/config.json`) — runtime knobs that are NOT schema
+ *  state (the on-disk schema version lives in manifest.json). Committed alongside
+ *  the graph, so a whole team shares the same settings — e.g. how firmly the
+ *  Claude Code agent hook enforces engineering memory before an edit. */
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+export const FIRMNESS_LEVELS = ["off", "advisory", "firm", "strict"];
+export const DEFAULT_FIRMNESS = "advisory";
+function defaults() {
+    return { firmness: DEFAULT_FIRMNESS };
+}
+export function isFirmness(v) {
+    return typeof v === "string" && FIRMNESS_LEVELS.includes(v);
+}
+/** Read `.hunch/config.json`. A missing/unparseable file, or an unknown firmness
+ *  value, falls back to defaults — the hook must NEVER crash an edit over config. */
+export function readConfig(paths) {
+    if (!existsSync(paths.config))
+        return defaults();
+    try {
+        const raw = JSON.parse(readFileSync(paths.config, "utf8"));
+        return { firmness: isFirmness(raw.firmness) ? raw.firmness : DEFAULT_FIRMNESS };
+    }
+    catch {
+        return defaults();
+    }
+}
+/** Write `.hunch/config.json`, merging `patch` over the current on-disk config. */
+export function writeConfig(paths, patch) {
+    const next = { ...readConfig(paths), ...patch };
+    mkdirSync(dirname(paths.config), { recursive: true });
+    writeFileSync(paths.config, JSON.stringify(next, null, 2) + "\n");
+    return next;
+}
+//# sourceMappingURL=config.js.map

package/dist/core/hookpolicy.js

@@ -0,0 +1,22 @@
+/** Return a BlockingHit if editing `file` (repo-relative) hits a blocking
+ *  invariant directly or through its blast radius, else null. */
+export function blockingInScope(store, file) {
+    for (const c of store.checkConstraints(file)) {
+        if (c.severity === "blocking") {
+            return {
+                reason: `Hunch: editing ${file} would touch a BLOCKING invariant — "${c.statement}" (${c.id}). Do not proceed unless this change is meant to modify that invariant; otherwise preserve it.`,
+            };
+        }
+    }
+    for (const b of store.blastRadiusFiles(file)) {
+        for (const c of store.checkConstraints(b.file)) {
+            if (c.severity === "blocking") {
+                return {
+                    reason: `Hunch: ${file} is in the blast radius of a BLOCKING invariant — "${c.statement}" (${c.id}; via ${b.file}, ${b.via} depth ${b.depth}). Verify the invariant still holds before editing.`,
+                };
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=hookpolicy.js.map

package/dist/core/paths.js

@@ -10,6 +10,7 @@ export function hunchPaths(root) {
         hunch,
         sqlite: join(hunch, "hunch.sqlite"),
         manifest: join(hunch, "manifest.json"),
+        config: join(hunch, "config.json"),
         dir: (kind) => join(hunch, kind),
     };
 }

package/dist/integrations/claudemd.js

@@ -3,8 +3,8 @@
  * context loaded every session for free"). We own ONLY the region between the
  * HUNCH markers — any user-authored content outside it is preserved verbatim.
  */
-import { readFileSync, writeFileSync, existsSync } from "node:fs";
-import { join } from "node:path";
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
 const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
 const END = "<!-- HUNCH:END -->";
 export function renderHunchSection(store) {
@@ -45,20 +45,18 @@ export function renderHunchSection(store) {
     lines.push(END);
     return lines.join("\n");
 }
-/** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
-export function updateClaudeMd(root, store) {
-    const file = join(root, "CLAUDE.md");
-    const section = renderHunchSection(store);
+/** Insert/replace the marker-delimited HUNCH section in a markdown doc, preserving
+ *  all user-authored content outside the markers. Shared by CLAUDE.md, AGENTS.md,
+ *  and .github/copilot-instructions.md so every assistant gets the same grounding. */
+export function upsertSection(file, section, fallbackTitle) {
     let content = existsSync(file) ? readFileSync(file, "utf8") : "";
     const iStart = content.indexOf(START);
     const iEnd = content.indexOf(END);
     if (iStart >= 0 && iEnd > iStart) {
-        // clean both-marker case: replace in place, preserving surrounding content
         content = content.slice(0, iStart) + section + content.slice(iEnd + END.length);
     }
     else if (iStart >= 0 || iEnd >= 0) {
-        // partial/corrupt markers (only one survived, or out of order): strip every
-        // stray marker line, then append ONE clean section — never duplicate.
+        // partial/corrupt markers: strip stray marker lines, then append ONE clean section.
         const body = content.split("\n").filter((l) => !l.includes(START) && !l.includes(END)).join("\n").trimEnd();
         content = body ? `${body}\n\n${section}\n` : `${section}\n`;
     }
@@ -66,11 +64,16 @@ export function updateClaudeMd(root, store) {
         content = `${content.trimEnd()}\n\n${section}\n`;
     }
     else {
-        content = `# ${root.split("/").pop()}\n\n${section}\n`;
+        content = `${fallbackTitle}\n\n${section}\n`;
     }
+    mkdirSync(dirname(file), { recursive: true }); // e.g. .github/ for copilot-instructions
     writeFileSync(file, content);
     return file;
 }
+/** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
+export function updateClaudeMd(root, store) {
+    return upsertSection(join(root, "CLAUDE.md"), renderHunchSection(store), `# ${root.split("/").pop()}`);
+}
 function sev(s) {
     return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;
 }

package/dist/integrations/providers.js

@@ -0,0 +1,229 @@
+/**
+ * Multi-assistant compatibility (DESIGN §7, extended). The Hunch MCP server is
+ * client-agnostic — any MCP-capable assistant can call the `hunch_*` tools. The
+ * only per-tool difference is HOW each one is told to launch the server and where
+ * its ambient grounding lives. This module scaffolds those surfaces for the major
+ * assistants so the same `.hunch/` graph powers all of them:
+ *
+ *   Assistant   | MCP config              | root key       | grounding file
+ *   ------------|-------------------------|----------------|---------------------------------
+ *   Claude Code | .mcp.json               | mcpServers     | CLAUDE.md            (scaffold.ts)
+ *   Cursor      | .cursor/mcp.json        | mcpServers     | .cursor/rules/hunch.mdc
+ *   VS Code     | .vscode/mcp.json        | servers (+type)| .github/copilot-instructions.md
+ *   Codex CLI   | .codex/config.toml      | [mcp_servers.*]| AGENTS.md
+ *   (any other) | —                       | —              | AGENTS.md (cross-tool standard)
+ *
+ * Every writer MERGES into existing files (preserving other servers / user prose)
+ * and is idempotent, so re-running `hunch init` is safe.
+ */
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { renderHunchSection, upsertSection } from "./claudemd.js";
+/** Strip // line and block comments + trailing commas (JSONC → JSON). String-aware
+ *  (double-quoted, with escapes) so a // inside a value isn't mangled. VS Code's
+ *  .vscode/mcp.json is JSONC, so we must tolerate comments. */
+function stripJsonc(s) {
+    let out = "";
+    let inStr = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        const n = s[i + 1];
+        if (inStr) {
+            out += c;
+            if (c === "\\") {
+                out += n ?? "";
+                i++;
+                continue;
+            }
+            if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"') {
+            inStr = true;
+            out += c;
+            continue;
+        }
+        if (c === "/" && n === "/") {
+            while (i < s.length && s[i] !== "\n")
+                i++;
+            continue;
+        }
+        if (c === "/" && n === "*") {
+            i += 2;
+            while (i < s.length && !(s[i] === "*" && s[i + 1] === "/"))
+                i++;
+            i++;
+            continue;
+        }
+        out += c;
+    }
+    return dropTrailingCommas(out);
+}
+/** Remove trailing commas (`,` before `}`/`]`) — string-aware, so a comma inside
+ *  a string value (e.g. "a,]") is never touched. A blanket regex would corrupt it
+ *  (the same trap test/migrate.test.ts guards against). Runs on comment-free text,
+ *  so lookahead need only skip whitespace. */
+function dropTrailingCommas(s) {
+    let out = "";
+    let inStr = false;
+    let esc = false;
+    for (let i = 0; i < s.length; i++) {
+        const c = s[i];
+        if (inStr) {
+            out += c;
+            if (esc)
+                esc = false;
+            else if (c === "\\")
+                esc = true;
+            else if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"') {
+            inStr = true;
+            out += c;
+            continue;
+        }
+        if (c === ",") {
+            let j = i + 1;
+            while (j < s.length && /\s/.test(s[j]))
+                j++;
+            if (s[j] === "}" || s[j] === "]")
+                continue; // trailing comma → drop
+        }
+        out += c;
+    }
+    return out;
+}
+/** Read a JSON/JSONC object. Returns {} only for an ABSENT or empty file. A
+ *  non-empty file we cannot parse THROWS — overwriting it would silently wipe the
+ *  user's other MCP servers. */
+function readJsonObj(file) {
+    if (!existsSync(file))
+        return {};
+    const raw = readFileSync(file, "utf8");
+    if (!raw.trim())
+        return {};
+    try {
+        const v = JSON.parse(stripJsonc(raw));
+        if (v && typeof v === "object" && !Array.isArray(v))
+            return v;
+        throw new Error("not a JSON object");
+    }
+    catch (e) {
+        throw new Error(`refusing to overwrite ${file}: could not parse it (${e.message}). Fix or remove it, then re-run.`);
+    }
+}
+/** Render a string as a TOML value: a literal '…' when safe (no escaping needed —
+ *  ideal for Windows backslash paths), else a basic "…" with escapes. */
+function tomlStr(s) {
+    // TOML literal '…' needs no escaping (ideal for Windows backslash paths) but
+    // can't contain a quote or newline; otherwise a basic "…" with escapes.
+    if (!/['\r\n]/.test(s))
+        return `'${s}'`;
+    const esc = s
+        .replace(/\\/g, "\\\\")
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, "\\n")
+        .replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+    return `"${esc}"`;
+}
+function writeJson(file, obj) {
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, JSON.stringify(obj, null, 2) + "\n");
+    return file;
+}
+/** Cursor: .cursor/mcp.json — same `mcpServers` shape as Claude Desktop/Code. */
+export function writeCursorMcp(root, inv) {
+    const file = join(root, ".cursor", "mcp.json");
+    const json = readJsonObj(file);
+    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
+    return writeJson(file, json);
+}
+/** VS Code (Copilot agent mode): .vscode/mcp.json — root key is `servers`, and
+ *  each stdio entry carries an explicit `type: "stdio"` (VS Code's schema). */
+export function writeVscodeMcp(root, inv) {
+    const file = join(root, ".vscode", "mcp.json");
+    const json = readJsonObj(file);
+    json.servers = json.servers ?? {};
+    json.servers.hunch = { type: "stdio", command: inv.command, args: [...inv.args, "mcp"] };
+    return writeJson(file, json);
+}
+const TOML_START = "# >>> hunch mcp (managed) >>>";
+const TOML_END = "# <<< hunch mcp <<<";
+/** Codex CLI: .codex/config.toml — `[mcp_servers.hunch]` stdio entry. We own only
+ *  a marker-delimited block; any other TOML the user has is preserved. Paths use
+ *  TOML single-quote LITERAL strings so Windows backslashes need no escaping. */
+export function writeCodexConfig(root, inv) {
+    const file = join(root, ".codex", "config.toml");
+    const argsToml = [...inv.args, "mcp"].map(tomlStr).join(", ");
+    const block = [
+        TOML_START,
+        "[mcp_servers.hunch]",
+        `command = ${tomlStr(inv.command)}`,
+        `args = [${argsToml}]`,
+        TOML_END,
+    ].join("\n");
+    // Strip any prior managed block first, so `base` is the user's own TOML.
+    const content = existsSync(file) ? readFileSync(file, "utf8") : "";
+    const i = content.indexOf(TOML_START);
+    const j = content.indexOf(TOML_END);
+    let base;
+    if (i >= 0 && j > i)
+        base = content.slice(0, i) + content.slice(j + TOML_END.length);
+    else if (i >= 0 || j >= 0)
+        base = content.split("\n").filter((l) => !l.includes(TOML_START) && !l.includes(TOML_END)).join("\n");
+    else
+        base = content;
+    // A user-authored [mcp_servers.hunch] outside our block would make TWO tables of
+    // the same name → TOML duplicate-table error. Refuse rather than corrupt it.
+    if (/^\s*\[mcp_servers\.hunch\]/m.test(base)) {
+        throw new Error(`refusing to edit ${file}: it already defines [mcp_servers.hunch] outside Hunch's managed block. Remove it, then re-run.`);
+    }
+    base = base.trimEnd();
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, base ? `${base}\n\n${block}\n` : `${block}\n`);
+    return file;
+}
+/** AGENTS.md — the cross-tool ambient-instruction standard (Codex and a growing
+ *  set of assistants read it). Marker-delimited so user prose is preserved. */
+export function writeAgentsMd(root, store) {
+    return upsertSection(join(root, "AGENTS.md"), renderHunchSection(store), "# AGENTS.md");
+}
+/** GitHub Copilot custom instructions (VS Code / github.com). Same grounding. */
+export function writeCopilotInstructions(root, store) {
+    return upsertSection(join(root, ".github", "copilot-instructions.md"), renderHunchSection(store), "# Copilot instructions");
+}
+/** Cursor project rule (.mdc = frontmatter + body). `alwaysApply` keeps the Hunch
+ *  grounding in context for every request. Fully managed by Hunch (overwritten). */
+export function writeCursorRule(root, store) {
+    const file = join(root, ".cursor", "rules", "hunch.mdc");
+    const body = `---\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\nalwaysApply: true\n---\n\n${renderHunchSection(store)}\n`;
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, body);
+    return file;
+}
+/** Scaffold MCP config + grounding for all supported assistants. Returns a
+ *  per-assistant summary for `hunch init` to print. Each assistant is isolated:
+ *  a writer that refuses to clobber a malformed file degrades to a warning rather
+ *  than aborting the rest. Claude Code is handled separately by scaffold.ts. */
+export function scaffoldProviders(root, inv, store) {
+    const tasks = [
+        ["Cursor", () => [writeCursorMcp(root, inv), writeCursorRule(root, store)]],
+        ["VS Code (Copilot)", () => [writeVscodeMcp(root, inv), writeCopilotInstructions(root, store)]],
+        ["Codex CLI", () => [writeCodexConfig(root, inv)]],
+        ["Any (AGENTS.md)", () => [writeAgentsMd(root, store)]],
+    ];
+    return tasks.map(([assistant, run]) => {
+        try {
+            return { assistant, files: run() };
+        }
+        catch (e) {
+            return { assistant, files: [], error: e.message };
+        }
+    });
+}
+//# sourceMappingURL=providers.js.map

package/dist/integrations/scaffold.js

@@ -4,7 +4,7 @@
  *   - .claude/commands/* → user-triggered slash commands for the §5 workflows
  */
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { join, dirname } from "node:path";
 /** Merge a `hunch` server entry into .mcp.json, preserving other servers. */
 export function writeMcpJson(root, inv) {
     const file = join(root, ".mcp.json");
@@ -55,6 +55,62 @@ then produce a **fragility report with evidence**: the specific files/functions,
 the bug history behind them, their churn and fan-in, and any missing guards.
 Avoid generic advice — every claim must cite a Hunch record or metric.
 `;
+/** A settings.json hook entry is Hunch's if any of its commands ends with the
+ *  Hunch CLI entry + the `hook` subcommand (e.g. `…/index.js hook`). Matching the
+ *  command TAIL — not the absolute path — makes re-init idempotent AND survives a
+ *  repo-folder rename (the path before index.js changes; the tail does not). The
+ *  leading path separator (`/` or `\`) requires `index` to be a full path segment,
+ *  so a foreign tool's `…/myindex.js hook` isn't mistaken for ours and clobbered. */
+function isHunchHook(entry) {
+    return !!entry.hooks?.some((h) => typeof h.command === "string" && /[\\/]index\.(js|ts)"?\s+hook\s*$/.test(h.command));
+}
+/**
+ * Install the Claude Code AGENT hooks into `.claude/settings.json` so the agent
+ * is grounded in Hunch automatically (not by remembering to call the tools):
+ *   - PreToolUse (Edit|Write|MultiEdit) → inject the relevant Hunch slice before
+ *     an edit, and (at strict firmness) deny edits that hit a blocking invariant.
+ *   - UserPromptSubmit → remind the agent to consult Hunch.
+ * Both invoke `hunch hook`, which reads the firmness level from .hunch/config.json
+ * at run time — so changing firmness needs no settings.json edit. We own only our
+ * entries (matched by isHunchHook): other hooks and settings are preserved, and a
+ * non-empty file we cannot parse THROWS rather than clobbering the user's config.
+ */
+export function installClaudeHooks(root, hookCmd) {
+    const file = join(root, ".claude", "settings.json");
+    const existed = existsSync(file);
+    let json = {};
+    let before = "";
+    if (existed) {
+        before = readFileSync(file, "utf8");
+        if (before.trim()) {
+            try {
+                const v = JSON.parse(before);
+                if (!v || typeof v !== "object" || Array.isArray(v))
+                    throw new Error("not a JSON object");
+                json = v;
+            }
+            catch (e) {
+                throw new Error(`refusing to overwrite ${file}: could not parse it (${e.message}). Fix or remove it, then re-run.`);
+            }
+        }
+    }
+    json.hooks = json.hooks ?? {};
+    const keep = (arr) => (Array.isArray(arr) ? arr.filter((e) => !isHunchHook(e)) : []);
+    json.hooks.PreToolUse = [
+        ...keep(json.hooks.PreToolUse),
+        { matcher: "Edit|Write|MultiEdit", hooks: [{ type: "command", command: hookCmd }] },
+    ];
+    json.hooks.UserPromptSubmit = [
+        ...keep(json.hooks.UserPromptSubmit),
+        { hooks: [{ type: "command", command: hookCmd }] },
+    ];
+    const next = JSON.stringify(json, null, 2) + "\n";
+    if (existed && before === next)
+        return { path: file, action: "unchanged" };
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileSync(file, next);
+    return { path: file, action: existed ? "updated" : "created" };
+}
 export function writeSlashCommands(root) {
     const dir = join(root, ".claude", "commands");
     mkdirSync(dir, { recursive: true });

package/dist/mcp/server.js

@@ -38,6 +38,12 @@ function resolveSymbols(store, target) {
         return byName;
     return syms.filter((s) => s.file === target || s.file.endsWith(target));
 }
+/** Resolve a target to canonical indexed file path(s) (for file-granular blast
+ *  radius). Falls back to the literal target so direct-scope checks still run. */
+function resolveFiles(store, target) {
+    const files = new Set(resolveSymbols(store, target).map((s) => s.file));
+    return files.size ? [...files] : [target];
+}
 export function buildServer(root) {
     const store = new HunchStore(hunchPaths(root));
     // Ensure the SQLite index reflects the JSON source of truth on startup.
@@ -143,6 +149,35 @@ export function buildServer(root) {
         const lines = deps.slice(0, DEP_CAP).map((d) => `  • [depth ${d.depth}] ${d.via} (${d.id})`);
         return ok(`Blast radius of "${symbol}" — ${deps.length} dependent(s):\n${lines.join("\n")}${more(deps.length, DEP_CAP, "closest shown first")}`);
     });
+    // -- hunch_blast_radius (dependents + near-violations) --------------------
+    server.registerTool("hunch_blast_radius", {
+        title: "Blast radius + near-violations for a file",
+        description: "Given a file you're about to change, return its dependency blast radius (files whose code depends on it) AND any invariants reached THROUGH that radius — 'near-violations' you could break indirectly without touching their own scope. Call before editing a widely-depended-on file. Mirrors `hunch check --blast`.",
+        inputSchema: { target: z.string().describe("A file path (e.g. src/auth/jwt.ts) or symbol.") },
+    }, async ({ target }) => {
+        const parts = [];
+        for (const file of resolveFiles(store, target)) {
+            const blast = store.blastRadiusFiles(file);
+            const directIds = new Set(store.checkConstraints(file).map((c) => c.id));
+            const near = new Map();
+            for (const b of blast) {
+                for (const c of store.checkConstraints(b.file)) {
+                    if (directIds.has(c.id) || near.has(c.id))
+                        continue;
+                    near.set(c.id, { c, via: `${b.file} (${b.via}, depth ${b.depth})` });
+                }
+            }
+            const blastBody = blast.length
+                ? `:\n${blast.slice(0, DEP_CAP).map((b) => `  • [depth ${b.depth}] ${b.file} (via ${b.via})`).join("\n")}${more(blast.length, DEP_CAP, "closest first")}`
+                : "";
+            const nearArr = [...near.values()];
+            const nearBody = nearArr.length
+                ? `\n  NEAR-VIOLATIONS (invariants reachable via this radius — review before editing):\n${nearArr.map((n) => `    ⚠ ${n.c.id} [${n.c.severity}] ${n.c.statement}\n        via ${n.via}`).join("\n")}`
+                : "\n  No invariants in the blast radius.";
+            parts.push(`${file} → ${blast.length} dependent file(s)${blastBody}${nearBody}`);
+        }
+        return ok(`Blast radius for "${target}":\n\n${parts.join("\n\n")}`);
+    });
     // -- hunch_context (surgical retrieval) -----------------------------------
     server.registerTool("hunch_context", {
         title: "Assemble the minimal relevant Hunch slice for a task",

package/dist/synthesis/provider.js

@@ -132,9 +132,55 @@ const BUG_TOOL = {
     },
 };
 // --------------------------------------------------------------------------
+// Base for headless-CLI SUBSCRIPTION providers. Each one drives a coding-assistant
+// CLI billed to the user's own subscription (never a pay-per-token API key — see
+// dec_5a7c0733f7). The prompt always goes over STDIN (never argv — keeps untrusted
+// diff content out of any shell pexecIn uses on Windows), and the CLI's text output
+// is handed to the SAME mappers, so the rest of the system is provider-agnostic.
+// --------------------------------------------------------------------------
+class CliSynthProvider {
+    /** Run a CLI with the prompt on stdin, stripping API-key env vars so the tool
+     *  falls through to its SUBSCRIPTION credentials. Shared by codex/cursor. */
+    async runCli(bin, args, stripEnv, prompt, timeoutMs = 120_000) {
+        const env = { ...process.env };
+        for (const k of stripEnv)
+            delete env[k];
+        const { stdout } = await pexecIn(bin, args, {
+            input: prompt,
+            env,
+            cwd: tmpdir(),
+            maxBuffer: 16 * 1024 * 1024,
+            timeout: timeoutMs,
+        });
+        return stdout;
+    }
+    async draftDecision(input) {
+        const text = await this.run(`${SYSTEM}\n\n${commitPrompt(input)}\n\n${jsonInstruction(DECISION_TOOL.input_schema)}`);
+        const draft = decisionDraftFromText(text, input.subject);
+        // No usable LLM JSON (truncation, refusal, prose-only, or a CLI whose output
+        // shape we misread) → THROW so the safe wrapper falls back to the deterministic
+        // provider, whose draft is honestly labeled ("inferred", low confidence).
+        if (!draft)
+            throw new Error(`${this.name}: no usable decision JSON in output`);
+        // For a LARGE diff the model only saw the structured summary + a sample — haircut
+        // the confidence and tag the source so provenance stays honest.
+        if (input.diff.length > LARGE_DIFF_CHARS) {
+            return { ...draft, confidence: Math.min(draft.confidence, 0.5), source: `${draft.source}+summary` };
+        }
+        return draft;
+    }
+    async draftBug(input) {
+        const text = await this.run(`${SYSTEM}\n\n${failurePrompt(input)}\n\n${jsonInstruction(BUG_TOOL.input_schema)}`);
+        const draft = bugDraftFromText(text, input.test, input.message);
+        if (!draft)
+            throw new Error(`${this.name}: no usable bug JSON in output`);
+        return draft;
+    }
+}
+// --------------------------------------------------------------------------
 // Provider A: headless `claude -p` CLI — billed to the user's Claude subscription
 // --------------------------------------------------------------------------
-class ClaudeCliProvider {
+class ClaudeCliProvider extends CliSynthProvider {
     name = "claude-cli";
     // Default to the `haiku` alias (cheap/fast, and survives model retirements)
     // rather than a pinned dated id; override with HUNCH_SYNTH_MODEL if needed.
@@ -190,31 +236,54 @@ class ClaudeCliProvider {
         }
         return envelope.result ?? stdout;
     }
-    async draftDecision(input) {
-        const text = await this.run(`${SYSTEM}\n\n${commitPrompt(input)}\n\n${jsonInstruction(DECISION_TOOL.input_schema)}`);
-        const draft = decisionDraftFromText(text, input.subject);
-        // No usable LLM JSON (truncation, refusal, prose-only) → THROW so the safe
-        // wrapper falls back to the deterministic provider, whose diff-structured
-        // draft is both more useful AND honestly labeled ("inferred", low confidence)
-        // than a hollow record mislabeled as an LLM draft.
-        if (!draft)
-            throw new Error("claude-cli: no usable decision JSON in output");
-        // For a LARGE diff the model only saw the structured summary + a sample, not
-        // the full patch (commitPrompt → renderDiff). The "why" is therefore lower-
-        // fidelity than a draft made from the whole diff, so haircut the confidence
-        // and tag the source — keeping provenance honest (a summary-sourced draft must
-        // not masquerade as a full-fidelity llm_draft at 0.65).
-        if (input.diff.length > LARGE_DIFF_CHARS) {
-            return { ...draft, confidence: Math.min(draft.confidence, 0.5), source: `${draft.source}+summary` };
+}
+// --------------------------------------------------------------------------
+// Provider B1: OpenAI Codex CLI (`codex exec`) — billed to the ChatGPT subscription
+// --------------------------------------------------------------------------
+class CodexCliProvider extends CliSynthProvider {
+    name = "codex-cli";
+    model = process.env.HUNCH_CODEX_MODEL; // omit → codex uses its configured default
+    async available() {
+        try {
+            await pexecIn("codex", ["--version"], { timeout: 8000 });
+            return true;
+        }
+        catch {
+            return false;
         }
-        return draft;
     }
-    async draftBug(input) {
-        const text = await this.run(`${SYSTEM}\n\n${failurePrompt(input)}\n\n${jsonInstruction(BUG_TOOL.input_schema)}`);
-        const draft = bugDraftFromText(text, input.test, input.message);
-        if (!draft)
-            throw new Error("claude-cli: no usable bug JSON in output");
-        return draft;
+    async run(prompt) {
+        // `codex exec --json -` reads the prompt from STDIN (the `-`), emits JSONL
+        // events. Strip OPENAI_API_KEY so it uses ChatGPT (subscription) auth, not the
+        // pay-per-token API — consistent with the subscription-only rule.
+        const args = ["exec", "--json", ...(this.model ? ["-m", this.model] : []), "-"];
+        const out = await this.runCli("codex", args, ["OPENAI_API_KEY"], prompt);
+        return extractCodexText(out);
+    }
+}
+// --------------------------------------------------------------------------
+// Provider B2: Cursor Agent CLI (`cursor-agent -p`) — billed to the Cursor subscription
+// --------------------------------------------------------------------------
+class CursorCliProvider extends CliSynthProvider {
+    name = "cursor-agent";
+    model = process.env.HUNCH_CURSOR_MODEL;
+    async available() {
+        try {
+            await pexecIn("cursor-agent", ["--version"], { timeout: 8000 });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    async run(prompt) {
+        // `-p --output-format text` → final answer as plain text (no event stream to
+        // parse). `--trust` so it runs non-interactively. Prompt over stdin. Cursor's
+        // CLI uses the user's Cursor login (subscription) — no API key to strip.
+        const args = ["-p", "--output-format", "text", "--trust", ...(this.model ? ["-m", this.model] : [])];
+        // Shorter timeout than the others: cursor-agent -p is reported to hang in some
+        // headless setups; cap the stall before degrading to the deterministic provider.
+        return this.runCli("cursor-agent", args, [], prompt, 45_000);
     }
 }
 // --------------------------------------------------------------------------
@@ -269,23 +338,71 @@ export class DeterministicProvider {
         };
     }
 }
-const PROVIDERS = [new ClaudeCliProvider(), new DeterministicProvider()];
+/** Extract the final assistant message from `codex exec --json` output (newline-
+ *  delimited JSON events). Codex tags assistant turns as `item.type ==="agent_message"`,
+ *  but it ALSO emits `item.text` for reasoning and may append trailing events — so we
+ *  prefer the last AGENT message and only fall back to the last any-text when none is
+ *  tagged. If nothing parses, hand the raw output to the mapper (→ it finds the JSON
+ *  draft or throws → deterministic fallback). Tolerant by design: drift degrades, never crashes. */
+export function extractCodexText(out) {
+    const texts = [];
+    const agentTexts = [];
+    for (const line of out.split(/\r?\n/)) {
+        const t = line.trim();
+        if (!t.startsWith("{"))
+            continue;
+        try {
+            const o = JSON.parse(t);
+            const item = o.item;
+            const cand = (item?.text ?? o.text ?? o.message);
+            if (typeof cand === "string" && cand.trim()) {
+                texts.push(cand);
+                const ty = (item?.type ?? o.type);
+                if (typeof ty === "string" && /agent|assistant|message\b/.test(ty) && !/reason/.test(ty))
+                    agentTexts.push(cand);
+            }
+        }
+        catch {
+            /* not a JSON event line — skip */
+        }
+    }
+    if (agentTexts.length)
+        return agentTexts[agentTexts.length - 1];
+    return texts.length ? texts[texts.length - 1] : out;
+}
+// Priority order: try each subscription CLI, then the always-available heuristic.
+// HUNCH_SYNTH_PROVIDER forces one by name (claude-cli / codex-cli / cursor-agent /
+// deterministic).
+const PROVIDERS = [
+    new ClaudeCliProvider(),
+    new CodexCliProvider(),
+    new CursorCliProvider(),
+    new DeterministicProvider(),
+];
+// Availability rarely changes within a process (a CLI doesn't get installed mid-run),
+// and selectProvider() runs on every sync/recordFailure — so memoize each probe.
+// Especially matters in the long-lived MCP server and on machines with NO assistant
+// CLI, where an uncached pass spawns one failing `--version` per provider every time.
+const availCache = new Map();
+function isAvailable(p) {
+    let v = availCache.get(p.name);
+    if (!v) {
+        v = p.available().catch(() => false);
+        availCache.set(p.name, v);
+    }
+    return v;
+}
 /** Choose the first available provider, honoring HUNCH_SYNTH_PROVIDER override. */
 export async function selectProvider() {
     const forced = process.env.HUNCH_SYNTH_PROVIDER;
     if (forced) {
         const p = PROVIDERS.find((x) => x.name === forced);
-        if (p && (await p.available()))
+        if (p && (await isAvailable(p)))
             return p;
     }
     for (const p of PROVIDERS) {
-        try {
-            if (await p.available())
-                return p;
-        }
-        catch {
-            /* try next */
-        }
+        if (await isAvailable(p))
+            return p;
     }
     return new DeterministicProvider();
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.4.0",
+  "version": "0.8.0",
   "license": "MIT",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",