@davesheffer/hunch 1.5.0 → 1.7.0

package/README.md

@@ -31,7 +31,7 @@ That gap is where architectural drift starts:
 | Without Hunch | With Hunch |
 | --- | --- |
 | A refactor passes tests but bypasses a hard-won service boundary. | The change is checked against the decision, its constraint, and the incident behind it. |
-| A new coding session starts from scratch. | Claude Code, Cursor, Copilot, Windsurf, and Codex retrieve the same project memory over MCP. |
+| A new coding session starts from scratch. | Claude Code, Cursor, Copilot, Windsurf, Antigravity, and Codex retrieve the same project memory over MCP. |
 | A correction disappears into a chat transcript. | “Never do that again” becomes a scoped, auditable guard. |
 | Code review sees a diff, not the reason behind it. | Change Gate produces a PASS / WARN / BLOCK receipt with causal evidence. |
 
@@ -55,18 +55,26 @@ and an optional pull-request guard.
 
 ## One graph. Every assistant. No lock-in.
 
-Hunch is agent-agnostic by design. It scaffolds MCP and grounding for Claude Code, Cursor, VS Code
-/ Copilot, Windsurf, Codex, and any agent that can read `AGENTS.md`.
+Hunch is agent-agnostic by design. It scaffolds MCP and grounding for Claude Code, Cursor, VS Code / Copilot,
+Windsurf, Google Antigravity, Codex, and any agent that can read `AGENTS.md`; where a client exposes hooks,
+it adds a native lifecycle adapter too.
 
 Your memory is plain JSON that you own. Hunch adds a SQLite index only as a rebuildable derived
 layer—your decisions never disappear into a proprietary hosted memory system.
 
+Synthesis is just as portable: Hunch can use Claude Code, Codex, or Cursor through the subscription
+CLI you choose. It never guesses which of several installed subscriptions to bill—set your local,
+gitignored preference with `hunch provider codex-cli` (or `claude-cli` / `cursor-agent`); otherwise
+Hunch uses a subscription only when exactly one is available, and falls back to deterministic local
+drafting when the choice is ambiguous.
+
 ```text
-Claude Code ─┐
-Cursor      ├── MCP ──> .hunch/ reasoning graph ──> deterministic checks
-Copilot     ┤
-Codex       ┤
-Windsurf   ─┘
+Claude Code  ─┐
+Cursor       ├── MCP ──> .hunch/ reasoning graph ──> deterministic checks
+Copilot      ┤
+Codex        ┤
+Windsurf     ┤
+Antigravity  ┘
 ```
 
 ## The Change Gate: review intent, not just code

package/dist/cli/index.js

@@ -28,7 +28,7 @@ import { selectEmbedder } from "../store/embedder.js";
 import { indexRepo } from "../extractors/indexer.js";
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
-import { selectProvider } from "../synthesis/provider.js";
+import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, } from "../synthesis/provider.js";
 import { isGitRepo, headSha, logSince, lastChangeDate, stagedFiles, workingFiles, commitFiles, asOfDate, stagedDiff, workingDiff, commitDiff, rangeFiles, rangeDiff, rangeSubjects, revExists, commitAndPushHunch, pullHunch, gitUntrackCached, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
 import { writeTeamConfig, ensureTeamOverlay, readTeamConfig } from "../integrations/team.js";
 import { runbookId, decisionId } from "../core/ids.js";
@@ -50,6 +50,7 @@ import { formatContext, formatStructure } from "../core/format.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpolicy.js";
 import { injectionMode } from "../core/hookcache.js";
+import { contextHookOutput, denyHookOutput, hookProvider, normalizeHookEvent, stopHookOutput } from "../core/agenthook.js";
 import { PIPELINE_LOOP, UNVERIFIED_NAG, loadPipelineState, onCommand, onEdit, onPrompt, onSkill, pipelineEnabled, savePipelineState, stopVerdict, } from "../core/pipeline.js";
 import { draftDuplicateOf } from "../core/dupdetect.js";
 import { planAutoReview, planMutations } from "../core/autoreview.js";
@@ -83,12 +84,12 @@ function storeFor() {
 // ---- init -----------------------------------------------------------------
 program
     .command("init")
-    .description("Scaffold .hunch/, index the repo, install the git hook, and wire up your coding assistants (Claude Code, Cursor, VS Code, Windsurf, Codex).")
+    .description("Scaffold .hunch/, index the repo, install the git hook, and wire up your coding assistants (Claude Code, Cursor, VS Code, Windsurf, Antigravity, Codex).")
     .option("--no-index", "skip the initial repo index")
     .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 direct, high-confidence, non-stale blocking invariant")
-    .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("--no-providers", "skip scaffolding non-Claude assistant configs (Cursor / VS Code / Windsurf / Antigravity / Codex / AGENTS.md)")
+    .option("--no-agent-hooks", "skip installing all assistant lifecycle hooks (MCP + grounding are still configured)")
     .option("--firmness <level>", "agent-hook firmness: off | advisory | firm | strict")
     .option("--private-sync", "post-commit synthesis writes captured decisions into the overlay repo (HUNCH_PRIVATE_DIR), never the public store")
     .option("--shared-sync", "alias of --private-sync (for teams using one shared overlay repo for any code repo)")
@@ -174,16 +175,16 @@ program
     // 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.
+    // Claude's native hooks run alongside provider-specific hooks below. Every
+    // adapter reads firmness at run time, so changing it needs no config rewrite.
     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.
+    // Multi-assistant compatibility: MCP + grounding + lifecycle adapters share
+    // the same .hunch/ graph across Cursor / VS Code / Windsurf / Antigravity.
     if (opts.providers !== false) {
-        const ps = scaffoldProviders(root, inv.mcp, store);
+        const ps = scaffoldProviders(root, inv.mcp, store, { agentHooks: opts.agentHooks !== false });
         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(", ")}`);
@@ -444,7 +445,20 @@ function configureOverlay(dir, opts, mode) {
     // a store elsewhere on disk. Resolution (env || local.json) re-resolves against root.
     const rel = relative(root, hunchDir);
     const stored = rel && !rel.startsWith("..") && !isAbsolute(rel) ? toPosixTarget(rel) : hunchDir;
-    writeFileAtomic(join(paths.hunch, "local.json"), JSON.stringify({ privateDir: stored, autoCommit: !!opts.autoCommit, mode }, null, 2) + "\n");
+    const localFile = join(paths.hunch, "local.json");
+    let existingLocal = {};
+    if (existsSync(localFile)) {
+        try {
+            const parsed = JSON.parse(readFileSync(localFile, "utf8"));
+            if (!parsed || Array.isArray(parsed) || typeof parsed !== "object")
+                throw new Error("not an object");
+            existingLocal = parsed;
+        }
+        catch {
+            return fail(`refusing to overwrite malformed local configuration: ${localFile}`);
+        }
+    }
+    writeFileAtomic(localFile, JSON.stringify({ ...existingLocal, privateDir: stored, autoCommit: !!opts.autoCommit, mode }, null, 2) + "\n");
     ensureGitignore(root); // keeps .hunch/local.json + .hunch-private/ out of git
     // SHARED mode with a remote: publish the store's URL in a COMMITTED team.json, so a
     // fresh clone / new teammate / headless agent auto-connects on `hunch init` (or MCP
@@ -1527,7 +1541,7 @@ program
 // ---- firmness (agent-hook enforcement level) ------------------------------
 program
     .command("firmness")
-    .description("Get or set how firmly the Claude Code agent hook enforces Hunch before edits.")
+    .description("Get or set how firmly agent lifecycle hooks enforce Hunch before edits.")
     .argument("[level]", "off | advisory | firm | strict (omit to print the current level)")
     .action((level) => {
     const paths = hunchPaths(findRoot());
@@ -1540,7 +1554,49 @@ program
         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).`);
+    console.log(`✓ firmness set to ${next} (takes effect on the next agent edit — no restart needed).`);
+});
+// ---- provider (per-user synthesis subscription choice) -------------------
+program
+    .command("provider")
+    .description("Show or set the local coding-assistant subscription Hunch may use for synthesis. Never changes team config.")
+    .argument("[name]", `auto | ${SYNTH_PREFERENCES.filter((p) => p !== "auto").join(" | ")} (omit to inspect)`)
+    .action(async (value) => {
+    const root = findRoot();
+    if (value != null) {
+        const preference = value.trim();
+        if (!SYNTH_PREFERENCES.includes(preference)) {
+            return fail(`provider must be one of: ${SYNTH_PREFERENCES.join(", ")}`);
+        }
+        try {
+            writeSynthesisPreference(root, preference);
+        }
+        catch (error) {
+            return fail(error instanceof Error ? error.message : String(error));
+        }
+        console.log(`✓ local synthesis preference set to ${preference} (gitignored; it never changes a teammate's billing choice).`);
+    }
+    const resolution = await resolveSynthesisProvider({ root });
+    const envValue = process.env.HUNCH_SYNTH_PROVIDER?.trim();
+    const local = readSynthesisPreference(root);
+    const hasValidEnv = !!envValue && SYNTH_PREFERENCES.includes(envValue);
+    console.log(`selected:    ${resolution.provider.name} (${resolution.source})`);
+    console.log(`preference:  ${hasValidEnv ? `environment: ${envValue}` : `local: ${local}`}`);
+    if (envValue && !hasValidEnv)
+        console.log(dim(`HUNCH_SYNTH_PROVIDER=${envValue} is unknown and is being ignored.`));
+    console.log("available:");
+    for (const status of resolution.statuses) {
+        const billing = status.subscription ? ` — ${status.subscription}` : "";
+        console.log(`  ${status.available ? "✓" : "·"} ${status.name}: ${status.label}${billing}`);
+    }
+    if (resolution.source === "ambiguous") {
+        const choices = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => `hunch provider ${s.name}`);
+        console.log(dim("Multiple subscription CLIs are available, so Hunch uses the free deterministic fallback rather than guessing which plan to spend."));
+        console.log(`choose one:  ${choices.join("  or  ")}`);
+    }
+    else if (resolution.source === "unavailable-preference") {
+        console.log(dim(`Your ${resolution.preference} preference is not available; Hunch is using the local deterministic fallback.`));
+    }
 });
 // ---- status (enforcement readiness at a glance) ---------------------------
 program
@@ -1581,16 +1637,22 @@ program
     console.log("");
     store.close();
 });
-// ---- hook (Claude Code agent-hook handler) --------------------------------
+// ---- hook (multi-agent lifecycle 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 () => {
+    .description("Agent-agnostic hook handler: normalizes Claude, VS Code, Cursor, Windsurf, and Antigravity events into Hunch context and strict policy checks. Reads hook JSON on stdin.")
+    .option("--provider <provider>", "hook event dialect: claude | vscode | cursor | windsurf | antigravity", "claude")
+    .action(async (opts) => {
     // 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 provider = hookProvider(opts.provider);
+        if (!provider)
+            return;
+        const evt = normalizeHookEvent(JSON.parse(await readStdin()), provider);
+        if (!evt)
+            return;
         const root = findRoot();
         const paths = hunchPaths(root);
         const firmness = readConfig(paths).firmness;
@@ -1620,7 +1682,7 @@ program
             const verdict = stopVerdict(st, firmness);
             if (verdict.block) {
                 savePipelineState(evt.session_id, verdict.state);
-                process.stdout.write(JSON.stringify({ decision: "block", reason: verdict.reason }));
+                emitStop(provider, verdict.reason);
             }
             return;
         }
@@ -1642,7 +1704,7 @@ program
             // different content, so it always comes through (dec_244397d920).
             if (injectionMode(evt.session_id, "prompt-reminder", text) === "delta")
                 return;
-            emitContext("UserPromptSubmit", text);
+            emitContext(provider, "UserPromptSubmit", text);
             return;
         }
         if (evt.hook_event_name === "SessionStart") {
@@ -1658,7 +1720,7 @@ program
                 if (!decisions.length) {
                     // Fresh graph: nothing to orient on, but the operating loop still ships.
                     if (pipelineEnabled())
-                        emitContext("SessionStart", PIPELINE_LOOP);
+                        emitContext(provider, "SessionStart", PIPELINE_LOOP);
                     return;
                 }
                 const L = [];
@@ -1678,7 +1740,13 @@ program
                 // (the zod bench showed ambient skills are read in ~0% of sessions).
                 if (pipelineEnabled())
                     L.push("", PIPELINE_LOOP);
-                emitContext("SessionStart", L.join("\n"));
+                const orientation = L.join("\n");
+                // Antigravity's nearest equivalent is PreInvocation, which can fire
+                // repeatedly in one conversation. Deduplicate it just like edit
+                // grounding so it remains an orientation, not a context flood.
+                if (provider === "antigravity" && injectionMode(evt.session_id, "orientation", orientation) === "delta")
+                    return;
+                emitContext(provider, "SessionStart", orientation);
             }
             finally {
                 s.close();
@@ -1710,7 +1778,7 @@ program
             const proposedLines = proposedEditLines(evt.tool_input);
             const deny = blockingInScope(store, target, proposedLines);
             if (deny) {
-                emitDeny(deny.reason);
+                emitDeny(provider, deny.reason);
                 return;
             }
             // Veto Guard (live): the proposed edit text re-introduces an approach an
@@ -1718,7 +1786,7 @@ program
             // only human-confirmed tripwires deny.
             const vetoDeny = proposedLines.length ? vetoInScope(store, target, proposedLines) : null;
             if (vetoDeny) {
-                emitDeny(vetoDeny.reason);
+                emitDeny(provider, vetoDeny.reason);
                 return;
             }
         }
@@ -1761,10 +1829,10 @@ program
         // the full 10-16KB block. Any record change re-sends the full text; the
         // strict-gate deny path above never routes through this (dec_244397d920).
         if (injectionMode(evt.session_id, `pre:${target}`, text) === "delta") {
-            emitContext("PreToolUse", `Hunch grounding for ${target}: unchanged this session (${ctx.decisions.length} decision(s), ${ctx.constraints.length} invariant(s) shown earlier — still current; hunch_why("${target}") to re-expand).`);
+            emitContext(provider, "PreToolUse", `Hunch grounding for ${target}: unchanged this session (${ctx.decisions.length} decision(s), ${ctx.constraints.length} invariant(s) shown earlier — still current; hunch_why("${target}") to re-expand).`);
             return;
         }
-        emitContext("PreToolUse", text);
+        emitContext(provider, "PreToolUse", text);
     }
     catch {
         // swallow — never block an edit on a hook failure
@@ -1952,7 +2020,7 @@ program
         // and any per-draft failure degrades to "not judged" (kept for a human).
         const verdicts = new Map();
         if (opts.llm !== false && !opts.private) {
-            const provider = await selectProvider();
+            const provider = await selectProvider({ root });
             if (provider.judgeDraft) {
                 // The candidate pool for duplicate_of / restatement: the LIVE, vouched records.
                 const existing = all
@@ -2271,7 +2339,7 @@ program
         let prose;
         let adoptionProse;
         if (opts.llm !== false) {
-            const provider = await selectProvider();
+            const provider = await selectProvider({ root });
             if (provider.draftProse) {
                 console.log(`Prose via ${provider.name} (subscription); the drift-bearing skeleton stays deterministic.`);
                 prose = (pack, excerpts) => provider.draftProse(wikiPrompt(pack, excerpts));
@@ -2503,24 +2571,24 @@ program
     const onDisk = readManifest(hunchPaths(root)).schema_version;
     const schemaNote = onDisk === SCHEMA_VERSION ? "" : onDisk > SCHEMA_VERSION ? `  ⚠ newer than this Hunch (v${SCHEMA_VERSION}) — upgrade hunch` : `  ⚠ run \`hunch migrate\``;
     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 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)` : ``));
+    const resolution = await resolveSynthesisProvider({ root });
+    const provider = resolution.provider;
+    console.log(`synthesis:  ${provider.name} (${resolution.source})`);
+    const selected = resolution.statuses.find((s) => s.name === provider.name);
+    if (selected?.subscription) {
+        console.log(`            ↳ LLM synthesis uses your ${selected.subscription}; provider API credentials are not used.`);
+    }
+    else if (resolution.source === "ambiguous") {
+        const names = resolution.statuses.filter((s) => s.name !== "deterministic" && s.available).map((s) => s.name);
+        console.log(dim(`            ↳ ${names.join(", ")} are available; Hunch will not guess which subscription to spend.`));
+        console.log(dim(`              choose one locally: ${names.map((name) => `hunch provider ${name}`).join("  or  ")}`));
+    }
+    else if (resolution.source === "unavailable-preference") {
+        console.log(dim(`            ↳ ${resolution.preference} was selected but is unavailable; using the offline heuristic.`));
     }
     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\`)`));
+        console.log(dim(`            ↳ no assistant CLI found — synthesis uses the offline heuristic (advisory, low-confidence).`));
+        console.log(dim(`              install or log into Claude Code, Codex, or Cursor; then select one with \`hunch provider <name>\`.`));
     }
     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`);
@@ -2657,13 +2725,22 @@ function realpathNorm(p) {
 function toRepoRel(root, abs) {
     return relative(realpathNorm(root), realpathNorm(abs)).split("\\").join("/");
 }
-function emitContext(event, text) {
-    process.stdout.write(JSON.stringify({ hookSpecificOutput: { hookEventName: event, additionalContext: text } }));
+function emitContext(provider, event, text) {
+    const output = contextHookOutput(provider, event, text);
+    if (output)
+        process.stdout.write(JSON.stringify(output));
 }
-function emitDeny(reason) {
-    process.stdout.write(JSON.stringify({
-        hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason },
-    }));
+function emitDeny(provider, reason) {
+    const result = denyHookOutput(provider, reason);
+    if (result.output)
+        process.stdout.write(JSON.stringify(result.output));
+    if (result.stderr)
+        process.stderr.write(`${result.stderr}\n`);
+    if (result.exitCode !== undefined)
+        process.exitCode = result.exitCode;
+}
+function emitStop(provider, reason) {
+    process.stdout.write(JSON.stringify(stopHookOutput(provider, reason)));
 }
 program.parseAsync().catch((e) => {
     try {

package/dist/core/agenthook.js

@@ -0,0 +1,197 @@
+/**
+ * Provider hook dialects → Hunch's one internal event shape.
+ *
+ * Hook payloads are an integration boundary: every provider is free to rename
+ * fields or tools. Keep that variability here so the policy engine receives
+ * the same small, fail-open shape regardless of the assistant that emitted it.
+ */
+export const HOOK_PROVIDERS = ["claude", "vscode", "windsurf", "antigravity", "cursor"];
+function obj(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function str(value) {
+    return typeof value === "string" && value.trim() ? value : undefined;
+}
+function stringAt(input, ...keys) {
+    for (const key of keys) {
+        const value = str(input[key]);
+        if (value)
+            return value;
+    }
+    return undefined;
+}
+function hunchToolName(name, input) {
+    if (!name)
+        return undefined;
+    const lower = name.toLowerCase();
+    if (/multi.*(edit|replace)|edit.*files|multi_replace/.test(lower))
+        return "MultiEdit";
+    if (/^(edit|strreplace|replace_string_in_file|replace_file_content)$/.test(lower) || /replace.*(string|content)/.test(lower))
+        return "Edit";
+    if (/^(write|create|create_file|write_to_file)$/.test(lower) || /write.*file/.test(lower))
+        return "Write";
+    if (/(shell|bash|terminal|run_command|run.*command|powershell)/.test(lower))
+        return "Bash";
+    if (/skill/.test(lower))
+        return "Skill";
+    // A provider can call an edit tool something new. A file path plus proposed
+    // content is enough to safely treat it as a write for policy purposes.
+    if (input.file_path && (input.new_string || input.content || input.edits?.length))
+        return "Edit";
+    return name;
+}
+function edits(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const normalized = value
+        .map((item) => obj(item))
+        .filter((item) => !!item)
+        .map((item) => ({ new_string: stringAt(item, "new_string", "newString", "ReplacementContent", "replacementContent") }));
+    return normalized.length ? normalized : undefined;
+}
+function normalizeToolInput(value) {
+    const raw = obj(value);
+    if (!raw)
+        return undefined;
+    const replacementChunks = Array.isArray(raw.ReplacementChunks) ? raw.ReplacementChunks : raw.replacementChunks;
+    const chunkEdits = Array.isArray(replacementChunks)
+        ? replacementChunks.map((chunk) => obj(chunk)).filter((chunk) => !!chunk)
+            .map((chunk) => ({ new_string: stringAt(chunk, "ReplacementContent", "replacementContent", "new_string", "newString") }))
+        : undefined;
+    const out = {
+        file_path: stringAt(raw, "file_path", "filePath", "path", "uri", "TargetFile", "targetFile", "AbsolutePath", "absolutePath"),
+        new_string: stringAt(raw, "new_string", "newString", "ReplacementContent", "replacementContent", "TargetContent", "targetContent"),
+        content: stringAt(raw, "content", "contents", "CodeContent", "codeContent"),
+        edits: edits(raw.edits) ?? edits(raw.files) ?? chunkEdits,
+        command: stringAt(raw, "command", "commandLine", "CommandLine", "cmd"),
+        skill: stringAt(raw, "skill", "skillName", "name"),
+    };
+    return Object.values(out).some((v) => v !== undefined) ? out : undefined;
+}
+function eventName(value, provider) {
+    if (typeof value !== "string")
+        return undefined;
+    const name = value.toLowerCase();
+    const map = {
+        pretooluse: "PreToolUse",
+        posttooluse: "PostToolUse",
+        userpromptsubmit: "UserPromptSubmit",
+        sessionstart: "SessionStart",
+        stop: "Stop",
+    };
+    if (map[name])
+        return map[name];
+    if (provider === "cursor") {
+        if (name === "beforesubmitprompt")
+            return "UserPromptSubmit";
+        if (name === "beforetoolexecution" || name === "beforefileedit" || name === "beforeshellexecution")
+            return "PreToolUse";
+        if (name === "afterfileedit" || name === "aftershellexecution")
+            return "PostToolUse";
+    }
+    if (provider === "windsurf") {
+        if (name === "pre_write_code" || name === "pre_run_command")
+            return "PreToolUse";
+        if (name === "post_write_code" || name === "post_run_command")
+            return "PostToolUse";
+        if (name === "pre_user_prompt")
+            return "UserPromptSubmit";
+    }
+    // Antigravity's PreInvocation is the lifecycle point which can inject a
+    // transient message before the model sees the turn. Internally it provides
+    // Hunch's session-orientation behavior.
+    if (provider === "antigravity" && name === "preinvocation")
+        return "SessionStart";
+    return undefined;
+}
+/** Parse a provider name supplied by a hook config. Unknown values intentionally
+ * return null so a bad config cannot make an edit fail. */
+export function hookProvider(value) {
+    return typeof value === "string" && HOOK_PROVIDERS.includes(value.toLowerCase())
+        ? value.toLowerCase()
+        : null;
+}
+/** Normalize a hook stdin payload. Unknown/malformed events return null and the
+ * CLI exits successfully without output — the Never Block on Hook Failure rule. */
+export function normalizeHookEvent(raw, provider) {
+    const input = obj(raw);
+    if (!input)
+        return null;
+    if (provider === "antigravity") {
+        const agEvent = input.toolCall ? "PreToolUse" : input.invocationNum !== undefined ? "PreInvocation" : input.executionNum !== undefined ? "Stop" : undefined;
+        const event = eventName(agEvent, provider);
+        if (!event)
+            return null;
+        const call = obj(input.toolCall);
+        const toolInput = normalizeToolInput(call?.args);
+        return {
+            hook_event_name: event,
+            session_id: stringAt(input, "conversationId"),
+            tool_name: hunchToolName(stringAt(call ?? {}, "name"), toolInput ?? {}),
+            tool_input: toolInput,
+        };
+    }
+    if (provider === "windsurf") {
+        const event = eventName(input.event ?? input.hook_event_name, provider);
+        if (!event)
+            return null;
+        const info = obj(input.tool_info) ?? obj(input.toolInput) ?? obj(input.tool_input);
+        const toolInput = normalizeToolInput(info);
+        return {
+            hook_event_name: event,
+            session_id: stringAt(input, "trajectory_id", "session_id", "sessionId"),
+            tool_name: hunchToolName(stringAt(input, "agent_action_name", "tool_name", "toolName"), toolInput ?? {}),
+            tool_input: toolInput,
+            prompt: stringAt(input, "prompt", "user_prompt", "userPrompt"),
+        };
+    }
+    const event = eventName(input.hook_event_name ?? input.hookEventName ?? input.event, provider);
+    if (!event)
+        return null;
+    const toolInput = normalizeToolInput(input.tool_input ?? input.toolInput);
+    return {
+        hook_event_name: event,
+        session_id: stringAt(input, "session_id", "sessionId", "conversation_id", "conversationId"),
+        tool_name: hunchToolName(stringAt(input, "tool_name", "toolName"), toolInput ?? {}),
+        tool_input: toolInput,
+        prompt: stringAt(input, "prompt", "user_prompt", "userPrompt"),
+    };
+}
+/** Provider-aware hook output. Context output is intentionally omitted for
+ * Windsurf because its documented hook protocol has no agent-context channel;
+ * its always-on project rule + MCP server remain the grounding delivery path. */
+export function contextHookOutput(provider, event, text) {
+    if (provider === "windsurf")
+        return null;
+    if (provider === "antigravity") {
+        return event === "SessionStart" ? { injectSteps: [{ ephemeralMessage: text }] } : { decision: "allow" };
+    }
+    if (provider === "cursor")
+        return { permission: "allow", agent_message: text };
+    return { hookSpecificOutput: { hookEventName: event, additionalContext: text } };
+}
+/** Strict-deny response in each native dialect. Windsurf uses documented exit
+ * code 2; the caller writes this error to stderr and preserves exit success for
+ * every accidental/malformed invocation. */
+export function denyHookOutput(provider, reason) {
+    if (provider === "windsurf")
+        return { output: null, exitCode: 2, stderr: reason };
+    if (provider === "antigravity")
+        return { output: { decision: "deny", reason } };
+    if (provider === "cursor")
+        return { output: { permission: "deny", user_message: reason, agent_message: reason } };
+    return {
+        output: { hookSpecificOutput: { hookEventName: "PreToolUse", permissionDecision: "deny", permissionDecisionReason: reason } },
+    };
+}
+/** Stop-gate output in each native dialect. */
+export function stopHookOutput(provider, reason) {
+    if (provider === "vscode")
+        return { continue: false, stopReason: reason };
+    if (provider === "cursor")
+        return { followup_message: reason };
+    if (provider === "antigravity")
+        return { decision: "continue", reason };
+    return { decision: "block", reason };
+}
+//# sourceMappingURL=agenthook.js.map

package/dist/core/config.js

@@ -1,7 +1,7 @@
 /** 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. */
+ *  agent lifecycle hooks enforce 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"];

package/dist/core/hookcache.js

@@ -4,7 +4,7 @@
  * 20+ times per session buries the agent's working context under repeats — the
  * cost of being grounded starts competing with the work.
  *
- * Mechanism: per Claude-Code session (the hook event carries session_id), keep
+ * Mechanism: per agent session (the hook event carries a provider-normalized session_id), keep
  * a tiny {key → content-hash} map in the OS tmpdir. First injection for a key
  * (or any time the underlying records CHANGE) → "full". Identical repeat →
  * "delta" (the caller emits a one-liner, or nothing).

package/dist/integrations/providers.js

@@ -137,6 +137,32 @@ function writeJson(file, obj) {
     writeFileSync(file, JSON.stringify(obj, null, 2) + "\n");
     return file;
 }
+/** Provider hook commands live in tracked config files, so use the structured
+ * invocation (the same portable npx package reference as MCP) rather than a
+ * machine-local CLI path. JSON quoting is accepted by POSIX shells and keeps
+ * paths with spaces intact for source/dev installs. */
+function hookCommand(inv, provider) {
+    return [...[inv.command], ...inv.args, "hook", "--provider", provider].map((part) => JSON.stringify(part)).join(" ");
+}
+function isHunchProviderHook(entry) {
+    const e = entry && typeof entry === "object" ? entry : null;
+    const command = typeof e?.command === "string" ? e.command : "";
+    return /(?:@davesheffer\/hunch|[\\/]index\.(?:js|ts))/.test(command) && /\bhook\b/.test(command);
+}
+/** Merge our command entries into a standard `{ hooks: { Event: [] } }` file.
+ * We replace only old Hunch commands and leave every foreign hook in place. */
+function writeHookConfig(file, entries) {
+    const json = readJsonObj(file);
+    const hooks = json.hooks && typeof json.hooks === "object" && !Array.isArray(json.hooks)
+        ? json.hooks
+        : {};
+    for (const [event, next] of Object.entries(entries)) {
+        const old = Array.isArray(hooks[event]) ? hooks[event] : [];
+        hooks[event] = [...old.filter((entry) => !isHunchProviderHook(entry)), ...next];
+    }
+    json.hooks = hooks;
+    return writeJson(file, json);
+}
 /** Cursor: .cursor/mcp.json — same `mcpServers` shape as Claude Desktop/Code. */
 export function writeCursorMcp(root, inv) {
     const file = join(root, ".cursor", "mcp.json");
@@ -154,15 +180,15 @@ export function writeVscodeMcp(root, inv) {
     json.servers.hunch = { type: "stdio", command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
-/** Google Antigravity's MCP config is GLOBAL (user home), not project-local — and the
- *  dir moved between versions (`antigravity/` vs `config/`). Resolve adaptively: an
- *  existing config wins, else an existing parent dir, else null (Antigravity not
- *  installed — we never create a global config for an absent tool). `home` is injectable
- *  for tests so we never touch the real ~/.gemini. */
+/** Google Antigravity's global MCP config moved between releases. Resolve
+ * adaptively: an existing config wins, else an existing parent dir, else null
+ * (Antigravity not installed — we never create a global config for an absent
+ * tool). The current project-local config is handled separately below. `home`
+ * is injectable for tests so we never touch the real ~/.gemini. */
 export function antigravityMcpFile(home = homedir()) {
     const candidates = [
-        join(home, ".gemini", "antigravity", "mcp_config.json"),
         join(home, ".gemini", "config", "mcp_config.json"),
+        join(home, ".gemini", "antigravity", "mcp_config.json"), // legacy
     ];
     for (const c of candidates)
         if (existsSync(c))
@@ -185,6 +211,16 @@ export function writeAntigravityMcp(inv, home = homedir()) {
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
+/** Current Antigravity IDE/CLI project config. Unlike a global config this is
+ * committed with the repository, so every clone gets the same private/local
+ * Hunch server without touching a user's home directory. */
+export function writeAntigravityWorkspaceMcp(root, inv) {
+    const file = join(root, ".agents", "mcp_config.json");
+    const json = readJsonObj(file);
+    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers.hunch = { 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
@@ -249,6 +285,22 @@ export function writeWindsurfMcp(root, inv) {
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
+/** Current Windsurf also discovers a user config at ~/.codeium/windsurf. Only
+ * touch it when the tool is already installed/configured; Hunch never creates a
+ * global configuration for an application the user does not have. */
+export function windsurfMcpFile(home = homedir()) {
+    const file = join(home, ".codeium", "windsurf", "mcp_config.json");
+    return existsSync(file) || existsSync(dirname(file)) ? file : null;
+}
+export function writeWindsurfGlobalMcp(inv, home = homedir()) {
+    const file = windsurfMcpFile(home);
+    if (!file)
+        return null;
+    const json = readJsonObj(file);
+    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
+    return writeJson(file, json);
+}
 /** Windsurf project rule (.windsurf/rules/hunch.md). `trigger: always_on` keeps the
  *  Hunch grounding in Cascade's context for every request. Fully managed (overwritten). */
 export function writeWindsurfRule(root, store) {
@@ -258,6 +310,86 @@ export function writeWindsurfRule(root, store) {
     writeFileSync(file, body);
     return file;
 }
+/** Cursor's hook API is beta, but its project-level config accepts this standard
+ * event map. Context delivery is opportunistic; the always-on rule and MCP
+ * registration remain the durable grounding path if a Cursor build suppresses
+ * a hook's agent_message. */
+export function writeCursorHooks(root, inv) {
+    const file = join(root, ".cursor", "hooks.json");
+    const command = hookCommand(inv, "cursor");
+    const written = writeHookConfig(file, {
+        sessionStart: [{ command }],
+        beforeSubmitPrompt: [{ command }],
+        preToolUse: [{ command }],
+        postToolUse: [{ command }],
+        stop: [{ command }],
+    });
+    const json = readJsonObj(written);
+    if (json.version === undefined) {
+        json.version = 1;
+        writeJson(written, json);
+    }
+    return written;
+}
+/** VS Code's native workspace hook location. It supports all lifecycle events
+ * Hunch needs and uses the same stdout contract as Claude Code, with different
+ * camelCase tool fields normalized in core/agenthook.ts. */
+export function writeVscodeHooks(root, inv) {
+    const file = join(root, ".github", "hooks", "hunch.json");
+    const command = hookCommand(inv, "vscode");
+    return writeHookConfig(file, {
+        SessionStart: [{ type: "command", command }],
+        UserPromptSubmit: [{ type: "command", command }],
+        PreToolUse: [{ type: "command", command }],
+        PostToolUse: [{ type: "command", command }],
+        Stop: [{ type: "command", command }],
+    });
+}
+/** Windsurf's documented workspace hooks. It only supports deterministic
+ * pre-hook blocking via exit code 2, so Hunch uses rules + MCP for context and
+ * reserves the hook for strict edit protection and pipeline observation. */
+export function writeWindsurfHooks(root, inv) {
+    const file = join(root, ".windsurf", "hooks.json");
+    const command = hookCommand(inv, "windsurf");
+    return writeHookConfig(file, {
+        pre_user_prompt: [{ command, show_output: false }],
+        pre_write_code: [{ command, show_output: false }],
+        post_write_code: [{ command, show_output: false }],
+        post_run_command: [{ command, show_output: false }],
+    });
+}
+function antigravityHandler(command) {
+    return { type: "command", command, timeout: 15 };
+}
+/** Antigravity keeps hook groups at the top level (not under `hooks`). Hunch
+ * owns only the `hunch` group and replaces its own old entries idempotently. */
+export function writeAntigravityHooks(root, inv) {
+    const file = join(root, ".agents", "hooks.json");
+    const json = readJsonObj(file);
+    const group = json.hunch && typeof json.hunch === "object" && !Array.isArray(json.hunch)
+        ? json.hunch
+        : {};
+    const command = hookCommand(inv, "antigravity");
+    const keep = (event) => Array.isArray(group[event])
+        ? group[event].filter((entry) => {
+            const e = entry && typeof entry === "object" ? entry : null;
+            if (isHunchProviderHook(e))
+                return false;
+            return !Array.isArray(e?.hooks) || !e.hooks.some((hook) => isHunchProviderHook(hook));
+        })
+        : [];
+    group.PreInvocation = [...keep("PreInvocation"), antigravityHandler(command)];
+    group.PreToolUse = [
+        ...keep("PreToolUse"),
+        {
+            matcher: "write_to_file|replace_file_content|multi_replace_file_content",
+            hooks: [antigravityHandler(command)],
+        },
+    ];
+    group.Stop = [...keep("Stop"), antigravityHandler(command)];
+    json.hunch = group;
+    return writeJson(file, json);
+}
 /** Rewrite the auto-maintained Hunch section in EVERY assistant grounding doc
  *  (CLAUDE.md, AGENTS.md, Copilot instructions, Cursor + Windsurf rules) from the
  *  current store — without touching the MCP/provider config files. `hunch private
@@ -300,28 +432,50 @@ export function refreshExistingGrounding(root, store) {
     }
     return changed;
 }
+/** A malformed configuration for one surface (for example an MCP file) must not
+ * prevent the same assistant's rule or lifecycle hook from being installed. */
+function runProvider(writers) {
+    const files = [];
+    const errors = [];
+    for (const write of writers) {
+        try {
+            const result = write();
+            files.push(...(Array.isArray(result) ? result : [result]));
+        }
+        catch (e) {
+            errors.push(e.message);
+        }
+    }
+    return { files, ...(errors.length ? { error: errors.join("; ") } : {}) };
+}
 /** 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) {
+export function scaffoldProviders(root, inv, store, options = {}) {
+    const hooks = options.agentHooks !== false;
+    const home = options.home;
     const tasks = [
-        ["Cursor", () => [writeCursorMcp(root, inv), writeCursorRule(root, store)]],
-        ["VS Code (Copilot)", () => [writeVscodeMcp(root, inv), writeCopilotInstructions(root, store)]],
-        ["Codex CLI", () => [writeCodexConfig(root, inv)]],
-        ["Windsurf", () => [writeWindsurfMcp(root, inv), writeWindsurfRule(root, store)]],
-        // Antigravity reads project-root AGENTS.md for grounding (written below); its MCP
-        // config is global + detection-gated, so it only writes when Antigravity is installed.
-        ["Google Antigravity", () => { const f = writeAntigravityMcp(inv); return f ? [f] : []; }],
-        ["Any (AGENTS.md)", () => [writeAgentsMd(root, store)]],
+        ["Cursor", () => runProvider([() => writeCursorMcp(root, inv), () => writeCursorRule(root, store), ...(hooks ? [() => writeCursorHooks(root, inv)] : [])])],
+        ["VS Code (Copilot)", () => runProvider([() => writeVscodeMcp(root, inv), () => writeCopilotInstructions(root, store), ...(hooks ? [() => writeVscodeHooks(root, inv)] : [])])],
+        ["Codex CLI", () => runProvider([() => writeCodexConfig(root, inv)])],
+        ["Windsurf", () => {
+                return runProvider([
+                    () => writeWindsurfMcp(root, inv),
+                    () => writeWindsurfRule(root, store),
+                    ...(hooks ? [() => writeWindsurfHooks(root, inv)] : []),
+                    () => { const global = writeWindsurfGlobalMcp(inv, home); return global ?? []; },
+                ]);
+            }],
+        ["Google Antigravity", () => {
+                return runProvider([
+                    () => writeAntigravityWorkspaceMcp(root, inv),
+                    ...(hooks ? [() => writeAntigravityHooks(root, inv)] : []),
+                    () => { const global = writeAntigravityMcp(inv, home); return global ?? []; },
+                ]);
+            }],
+        ["Any (AGENTS.md)", () => runProvider([() => writeAgentsMd(root, store)])],
     ];
-    return tasks.map(([assistant, run]) => {
-        try {
-            return { assistant, files: run() };
-        }
-        catch (e) {
-            return { assistant, files: [], error: e.message };
-        }
-    });
+    return tasks.map(([assistant, run]) => ({ assistant, ...run() }));
 }
 //# sourceMappingURL=providers.js.map

package/dist/synthesis/provider.js

@@ -1,23 +1,26 @@
 /**
  * Pluggable synthesis provider for the WRITE path (DESIGN.md §4 / §7).
  *
- * LLM synthesis is driven by the user's Claude **subscription** via the `claude`
- * CLI — never the pay-per-token Anthropic API. We try, in order:
- * claude-cli → deterministic-fallback. The fallback always works (no creds, no
- * network) and emits a LOW-confidence draft, honoring the design rule that
- * auto-captured memory is advisory and cheap to discard.
+ * LLM synthesis is driven by the user's chosen coding-assistant subscription
+ * CLI — never a pay-per-token API. Claude Code, Codex, and Cursor use different
+ * auth surfaces, but every provider returns the same shape. When more than one
+ * subscription CLI is available, Hunch deliberately does NOT guess whose plan
+ * to spend: the user chooses once with `hunch provider <name>` (stored locally)
+ * or overrides per shell with HUNCH_SYNTH_PROVIDER. Ambiguous auto mode stays
+ * deterministic and free.
  *
- * Subscription, not API: Claude Code's auth precedence puts `ANTHROPIC_API_KEY`
- * (and `ANTHROPIC_AUTH_TOKEN`) ABOVE subscription OAuth, and in headless `-p`
- * mode the API key is *always* used when present. So we strip those vars from
- * the child env (see ClaudeCliProvider.run) to force the CLI down to subscription
- * OAuth / CLAUDE_CODE_OAUTH_TOKEN. There is intentionally NO API-key provider.
+ * Subscription, not API: provider-specific API credentials are removed from the
+ * child env wherever the CLI would otherwise prefer them. There is intentionally
+ * NO direct API-key provider.
  *
  * Every provider returns the same shape so the rest of the system never knows
  * (or cares) which one ran.
  */
 import { spawn } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { writeFileAtomic } from "../core/io.js";
 import { summarizeDiff } from "../extractors/diff.js";
 const IS_WIN = process.platform === "win32";
 /**
@@ -96,6 +99,16 @@ export function pexecIn(cmd, args, opts = {}) {
         child.stdin.end();
     });
 }
+/** Every selectable synthesis mode. `auto` is a preference value rather than a
+ * provider: it uses a subscription only when exactly one usable CLI is found. */
+export const SYNTH_PROVIDER_NAMES = ["claude-cli", "codex-cli", "cursor-agent", "deterministic"];
+export const SYNTH_PREFERENCES = ["auto", ...SYNTH_PROVIDER_NAMES];
+const PROVIDER_INFO = {
+    "claude-cli": { label: "Claude Code", subscription: "Claude subscription" },
+    "codex-cli": { label: "Codex", subscription: "ChatGPT subscription" },
+    "cursor-agent": { label: "Cursor Agent", subscription: "Cursor subscription" },
+    deterministic: { label: "Deterministic local fallback", subscription: null },
+};
 const SYSTEM = `You are the synthesis engine of an Engineering Memory OS. You turn raw
 developer activity (a git commit diff, or a test failure) into a single structured
 "why" record. Be precise and evidence-grounded; never invent facts not supported by
@@ -169,7 +182,7 @@ const VERIFY_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
+// dec_65b058de66). 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.
 // --------------------------------------------------------------------------
@@ -447,9 +460,9 @@ export function extractCodexText(out) {
         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).
+// This registry is deliberately NOT a priority order. Auto mode only spends a
+// subscription when it can identify exactly one usable CLI; see
+// resolveSynthesisProvider below.
 const PROVIDERS = [
     new ClaudeCliProvider(),
     new CodexCliProvider(),
@@ -457,31 +470,126 @@ const PROVIDERS = [
     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();
+// and selection runs on every sync/recordFailure. Cache by object identity rather than
+// name so injected test registries never inherit a stale result from another provider.
+const availCache = new WeakMap();
 function isAvailable(p) {
-    let v = availCache.get(p.name);
+    let v = availCache.get(p);
     if (!v) {
         v = p.available().catch(() => false);
-        availCache.set(p.name, v);
+        availCache.set(p, 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 isAvailable(p)))
-            return p;
+function isSynthPreference(value) {
+    return !!value && SYNTH_PREFERENCES.includes(value);
+}
+function fallbackProvider(providers) {
+    return providers.find((p) => p.name === "deterministic") ?? new DeterministicProvider();
+}
+function localPreferencePath(root) {
+    return join(root, ".hunch", "local.json");
+}
+/** Read a per-user, gitignored choice. Invalid/missing local state is treated as auto;
+ * `writeSynthesisPreference` refuses to overwrite malformed data so this forgiveness
+ * never destroys someone else's local settings. */
+export function readSynthesisPreference(root) {
+    try {
+        const file = localPreferencePath(root);
+        if (!existsSync(file))
+            return "auto";
+        const parsed = JSON.parse(readFileSync(file, "utf8"));
+        return typeof parsed.synthProvider === "string" && isSynthPreference(parsed.synthProvider)
+            ? parsed.synthProvider
+            : "auto";
     }
-    for (const p of PROVIDERS) {
-        if (await isAvailable(p))
-            return p;
+    catch {
+        return "auto";
+    }
+}
+/** Persist the user's provider choice only in `.hunch/local.json`, which is never a
+ * repository policy. That means each developer controls their own subscription spend. */
+export function writeSynthesisPreference(root, preference) {
+    if (!isSynthPreference(preference))
+        throw new Error(`unknown synthesis provider preference: ${preference}`);
+    const file = localPreferencePath(root);
+    let local = {};
+    if (existsSync(file)) {
+        const raw = readFileSync(file, "utf8");
+        if (raw.trim()) {
+            try {
+                const parsed = JSON.parse(raw);
+                if (!parsed || Array.isArray(parsed) || typeof parsed !== "object")
+                    throw new Error("not an object");
+                local = parsed;
+            }
+            catch {
+                throw new Error(`refusing to overwrite malformed local configuration: ${file}`);
+            }
+        }
+    }
+    mkdirSync(dirname(file), { recursive: true });
+    writeFileAtomic(file, `${JSON.stringify({ ...local, synthProvider: preference }, null, 2)}\n`);
+}
+async function statusesFor(providers) {
+    const statuses = [];
+    for (const provider of providers) {
+        if (!SYNTH_PROVIDER_NAMES.includes(provider.name))
+            continue;
+        const name = provider.name;
+        const info = PROVIDER_INFO[name];
+        statuses.push({ name, ...info, available: await isAvailable(provider) });
+    }
+    return statuses;
+}
+/** Resolve the provider without ever inferring which of several installed products is
+ * the one the user intends to spend. Precedence is deliberate: a one-shell override,
+ * then a per-user local preference, then safe auto-detection. */
+export async function resolveSynthesisProvider(opts = {}) {
+    const providers = opts.providers ?? PROVIDERS;
+    const env = opts.env ?? process.env;
+    const statuses = await statusesFor(providers);
+    const fallback = fallbackProvider(providers);
+    const find = (name) => providers.find((p) => p.name === name);
+    const usable = async (name) => {
+        const provider = find(name);
+        return provider && await isAvailable(provider) ? provider : undefined;
+    };
+    const environment = env.HUNCH_SYNTH_PROVIDER?.trim();
+    if (environment && isSynthPreference(environment) && environment !== "auto") {
+        const selected = await usable(environment);
+        if (selected)
+            return { provider: selected, source: "environment", preference: environment, statuses };
+        return { provider: fallback, source: "unavailable-preference", preference: environment, statuses };
+    }
+    // `HUNCH_SYNTH_PROVIDER=auto` is useful in CI or a shell profile: it explicitly
+    // suppresses the local preference and re-enters the safe auto policy.
+    const preference = environment === "auto"
+        ? "auto"
+        : opts.root ? readSynthesisPreference(opts.root) : "auto";
+    if (preference !== "auto") {
+        const selected = await usable(preference);
+        if (selected)
+            return { provider: selected, source: "local", preference, statuses };
+        return { provider: fallback, source: "unavailable-preference", preference, statuses };
+    }
+    const available = statuses.filter((status) => status.name !== "deterministic" && status.available);
+    if (available.length === 1) {
+        const selected = await usable(available[0].name);
+        if (selected)
+            return { provider: selected, source: "single-available", preference, statuses };
     }
-    return new DeterministicProvider();
+    return {
+        provider: fallback,
+        source: available.length > 1 ? "ambiguous" : "none",
+        preference,
+        statuses,
+    };
+}
+/** The provider used by normal synthesis. See `resolveSynthesisProvider` for a
+ * diagnosable result with the selection source and every candidate's availability. */
+export async function selectProvider(opts = {}) {
+    return (await resolveSynthesisProvider(opts)).provider;
 }
 // ---- Deep Synthesis: ensemble of subscription CLIs ------------------------
 // Opt-in (backfill/sync --deep): fan a commit out to EVERY available subscription
@@ -490,9 +598,9 @@ export async function selectProvider() {
 // the guard path; confidence is capped below the strict gate so output stays advisory.
 /** All available subscription-CLI workers (claude/codex/cursor), excluding the
  *  deterministic fallback — the pool Deep Synthesis fans a commit out to. */
-export async function selectWorkers() {
+export async function selectWorkers(opts = {}) {
     const out = [];
-    for (const p of PROVIDERS) {
+    for (const p of opts.providers ?? PROVIDERS) {
         if (p.name === "deterministic")
             continue; // workers are real subscription CLIs only
         if (await isAvailable(p))
@@ -592,7 +700,7 @@ export class EnsembleProvider {
  *  (the caller then falls back to the normal single-provider path). `samples` sets
  *  the self-consistency depth for the single-CLI case. */
 export async function selectEnsemble(opts = {}) {
-    const workers = await selectWorkers();
+    const workers = await selectWorkers(opts);
     // The self-consistency policy default (DEFAULT_SAMPLES) is applied HERE, not in the
     // provider — so a single CLI under --deep is sampled N times, while direct
     // construction stays passthrough. `--samples 1` opts back out.
@@ -601,9 +709,9 @@ export async function selectEnsemble(opts = {}) {
 /** Pick a CLI provider to run the Critic pass (subscription-only, like the workers).
  *  Returns null when no assistant CLI is installed — verification then no-ops and the
  *  un-audited draft stands (graceful degradation; dec_18a81c8291). */
-export async function selectVerifier() {
-    const workers = await selectWorkers();
-    return workers[0] ?? null;
+export async function selectVerifier(opts = {}) {
+    const { provider } = await resolveSynthesisProvider(opts);
+    return provider.name === "deterministic" ? null : provider;
 }
 // ---- Verification (the Critic pass) ---------------------------------------
 // Audit a draft against the commit it came from, then PRUNE unsupported

package/dist/synthesis/synthesize.js

@@ -98,9 +98,9 @@ export async function syncCommit(store, root, sha, opts = {}) {
     const provider = localOnly
         ? new DeterministicProvider()
         : opts.deep
-            ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider()
+            ? (await selectEnsemble({ samples: opts.samples })) ?? await selectProvider({ root })
             : opts.force || opts.verify || isSignificant(meta, analysis, codeFiles)
-                ? await selectProvider()
+                ? await selectProvider({ root })
                 : new DeterministicProvider();
     const input = { subject: meta.subject, body: meta.body, files: codeFiles, diff, analysis };
     let draft = await draftDecisionSafe(provider, input);
@@ -108,7 +108,7 @@ export async function syncCommit(store, root, sha, opts = {}) {
     // (BEFORE they scaffold tripwires below) and consequences, and lower confidence on weak
     // grounding. No-ops when no assistant CLI is available; never raises trust (dec_9a2f2fe72a).
     if (wantVerify)
-        draft = await verifyDecisionSafe(await selectVerifier(), input, draft);
+        draft = await verifyDecisionSafe(await selectVerifier({ root }), input, draft);
     // Advisory synthesis telemetry for `hunch review` — which provider ran, how many drafts
     // were reconciled, their agreement, and the verifier's grounding. Rides in `evidence`
     // (no schema change → respects forward-migration invariant con_947c578b2c).
@@ -199,7 +199,7 @@ export async function recordFailure(store, root, failure, opts = {}) {
     // A private bug may contain a stack trace, customer data, or secrets. Keep the
     // whole capture local unless the caller deliberately routes it through a shared
     // (non-private) workflow.
-    const provider = opts.private ? new DeterministicProvider() : await selectProvider();
+    const provider = opts.private ? new DeterministicProvider() : await selectProvider({ root });
     const input = {
         test: failure.test,
         message: failure.message,

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.5.0",
+  "version": "1.7.0",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
-  "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Codex).",
+  "description": "Architectural Conformance for AI-generated code: a git-native graph that deterministically blocks AI changes which break your architecture — the semantic invariants (layering, must-reach, dependency direction) pattern-SAST can't express — grounded in the decisions and bugs behind each rule, across any MCP assistant (Claude Code, Cursor, Copilot, Windsurf, Antigravity, Codex).",
   "homepage": "https://hunch-pi.vercel.app",
   "repository": {
     "type": "git",
@@ -27,6 +27,10 @@
   },
   "keywords": [
     "claude-code",
+    "cursor",
+    "copilot",
+    "windsurf",
+    "antigravity",
     "mcp",
     "engineering-memory",
     "knowledge-graph",