@davesheffer/hunch 1.5.0 → 1.6.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,20 @@ 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.
 
 ```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

@@ -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(", ")}`);
@@ -1527,7 +1528,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 +1541,7 @@ 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).`);
 });
 // ---- status (enforcement readiness at a glance) ---------------------------
 program
@@ -1581,16 +1582,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 +1627,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 +1649,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 +1665,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 +1685,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 +1723,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 +1731,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 +1774,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
@@ -2657,13 +2670,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/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.5.0",
+  "version": "1.6.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",