@davesheffer/hunch 1.4.2 → 1.6.0

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/autoreview.js

@@ -0,0 +1,52 @@
+import { draftDuplicateOf } from "./dupdetect.js";
+import { parseSynth, isReady, READY_MIN_GROUNDED } from "./reviewqueue.js";
+const DEFAULT_MIN_REJECT_CONFIDENCE = 0.7;
+/** Build the plan. `verdicts` maps draft id → harness verdict (absent → the draft
+ *  was not judged, e.g. no CLI available; it can still be dup-rejected or kept). */
+export function planAutoReview(drafts, allDecisions, verdicts, cfg = {}) {
+    const minGrounded = cfg.minGrounded ?? READY_MIN_GROUNDED;
+    const minReject = cfg.minRejectConfidence ?? DEFAULT_MIN_REJECT_CONFIDENCE;
+    const plan = { accept: [], rejectDuplicate: [], rejectIrrelevant: [], keep: [] };
+    for (const d of drafts) {
+        const verdict = verdicts.get(d.id);
+        const synth = parseSynth(d.provenance?.evidence);
+        const grounded = synth.grounded;
+        const base = { d, verdict, grounded };
+        // 1) Duplicate — deterministic match against accepted records, or the harness
+        //    naming an existing decision. Deterministic wins first (cheapest, surest).
+        const detDup = draftDuplicateOf(d, allDecisions);
+        if (detDup) {
+            plan.rejectDuplicate.push({ ...base, action: "rejectDuplicate", reason: `near-duplicate of ${detDup.of.id} "${detDup.of.title}" (${Math.round(detDup.score * 100)}%)` });
+            continue;
+        }
+        if (verdict?.duplicate_of && verdict.duplicate_of !== d.id && allDecisions.some((x) => x.id === verdict.duplicate_of)) {
+            plan.rejectDuplicate.push({ ...base, action: "rejectDuplicate", reason: `harness: restates ${verdict.duplicate_of} — ${verdict.reason}` });
+            continue;
+        }
+        // 2) Confidently-irrelevant — delete only on a strong harness "no".
+        if (verdict && !verdict.relevant && verdict.confidence >= minReject) {
+            plan.rejectIrrelevant.push({ ...base, action: "rejectIrrelevant", reason: `harness: not relevant (conf ${verdict.confidence}) — ${verdict.reason}` });
+            continue;
+        }
+        // 3) Accept — ONLY when the Critic verified + grounded it (isReady) AND the
+        //    harness judged it relevant. The harness can VETO an accept, never create
+        //    one on its own (dec_a466655539: the human vouch / Critic gate is the floor).
+        const ready = isReady(d, synth, minGrounded);
+        if (ready && verdict?.relevant) {
+            plan.accept.push({ ...base, action: "accept", reason: `verified + grounded ${grounded ?? "?"} ≥ ${minGrounded}, harness-relevant — ${verdict.reason}` });
+            continue;
+        }
+        // 4) Keep for a human — the safe default (unverified, ungrounded, unjudged, or
+        //    a low-confidence irrelevant call).
+        const why = !verdict ? "not judged (no harness)"
+            : !ready ? (verdict.relevant ? "relevant but not Critic-verified/grounded — needs human confirm" : `irrelevant but low confidence (${verdict.confidence})`)
+                : "kept";
+        plan.keep.push({ ...base, action: "keep", reason: why });
+    }
+    return plan;
+}
+/** Total drafts the plan would mutate (accept + both delete buckets). */
+export function planMutations(plan) {
+    return plan.accept.length + plan.rejectDuplicate.length + plan.rejectIrrelevant.length;
+}
+//# sourceMappingURL=autoreview.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/drift.js

@@ -13,7 +13,7 @@
  *                 `hunch wiki --heal`, never a gate.
  */
 import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { toPosixTarget } from "./paths.js";
 import { currentForTopic, isLive } from "./topics.js";
 import { parseDocAnchors } from "./docanchors.js";
@@ -36,7 +36,7 @@ export function computeDrift(store, root) {
             for (const f of d.related_files ?? []) {
                 if (!f || f.includes("*"))
                     continue; // skip globs / empties
-                if (!existsSync(join(root, f))) {
+                if (!referenceExists(store, root, d.id, f)) {
                     findings.push({ kind: "dead-ref", id: d.id, detail: `references missing file "${f}"` });
                 }
             }
@@ -66,7 +66,7 @@ export function computeDrift(store, root) {
                 for (const f of d.related_files ?? []) {
                     if (!f || f.includes("*") || liveFiles.has(toPosixTarget(f)))
                         continue;
-                    if (!existsSync(join(root, f)))
+                    if (!referenceExists(store, root, d.id, f))
                         continue; // missing file is history → dead-ref's job
                     findings.push({
                         kind: "anchor-stale",
@@ -120,6 +120,28 @@ export function computeDrift(store, root) {
     findings.push(...computeWikiDrift(store, root));
     return { findings };
 }
+/** Resolve a decision file reference without making private-memory paths depend on
+ * the current machine's overlay location. Normal references are code-repo-relative.
+ * A `private:<path>` reference is valid only when the decision itself is in the
+ * private overlay and resolves from that overlay repo's root. This lets a private
+ * decision cite private docs while preventing a public record from silently
+ * depending on unsharable local files. */
+function referenceExists(store, root, decisionId, ref) {
+    const prefix = "private:";
+    if (!ref.startsWith(prefix))
+        return existsSync(join(root, ref));
+    const privatePath = ref.slice(prefix.length);
+    if (!privatePath || isAbsolute(privatePath) || !store.privateDir || !store.getPrivateRec("decisions", decisionId))
+        return false;
+    const privateRoot = dirname(store.privateDir);
+    const candidate = resolve(privateRoot, privatePath);
+    // A private-scoped reference is an overlay-repo-relative path, not an escape
+    // hatch into arbitrary local files.
+    const rel = relative(privateRoot, candidate);
+    if (rel === "" || rel === ".." || rel.startsWith(`..${process.platform === "win32" ? "\\\\" : "/"}`) || isAbsolute(rel))
+        return false;
+    return existsSync(candidate);
+}
 function safeRead(path) {
     try {
         return readFileSync(path, "utf8");

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/core/refrepair.js

@@ -0,0 +1,33 @@
+function replaceExact(values, from, to) {
+    let changed = 0;
+    const replaced = values.map((value) => {
+        if (value !== from)
+            return value;
+        changed++;
+        return to;
+    });
+    // A decision may already cite the destination. Keep the reference list a set
+    // after the repair so a correction cannot create duplicate scope/evidence.
+    return { values: [...new Set(replaced)], changed };
+}
+/**
+ * Return a corrected copy of a decision, or `null` when the source reference is
+ * not present. The decision's semantic content and verification timestamp are
+ * intentionally preserved: this repairs a locator, it does not re-approve intent.
+ */
+export function repairDecisionReference(decision, from, to) {
+    const files = replaceExact(decision.related_files, from, to);
+    const evidence = replaceExact(decision.provenance.evidence, from, to);
+    if (!files.changed && !evidence.changed)
+        return null;
+    return {
+        decision: {
+            ...decision,
+            related_files: files.values,
+            provenance: { ...decision.provenance, evidence: evidence.values },
+        },
+        relatedFiles: files.changed,
+        evidence: evidence.changed,
+    };
+}
+//# sourceMappingURL=refrepair.js.map

package/dist/extractors/git.js

@@ -2,7 +2,7 @@
  *  No LLM here — just parsing what git already knows. */
 import { execFileSync } from "node:child_process";
 import { isAbsolute, resolve, join, basename, dirname } from "node:path";
-import { mkdirSync, rmSync, statSync, realpathSync } from "node:fs";
+import { mkdirSync, rmSync, statSync, realpathSync, readFileSync } from "node:fs";
 function git(args, cwd, maxBuffer = 64 * 1024 * 1024) {
     // stdio: capture stdout, silence stderr (so "no commits yet" etc. don't leak).
     return execFileSync("git", args, {
@@ -377,6 +377,14 @@ export function stagedFiles(cwd) {
     const out = gitSafe(["diff", "--cached", "--name-only", "--diff-filter=ACMR"], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
+/** Files changed anywhere in the working tree compared with HEAD: both staged
+ * and unstaged tracked files, plus untracked files. This powers the local,
+ * pre-commit Change Gate; it never mutates the index or asks an agent/model. */
+export function workingFiles(cwd) {
+    const changed = gitSafe(["diff", "HEAD", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean);
+    const untracked = gitSafe(["ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter(Boolean);
+    return [...new Set([...changed, ...untracked])].sort();
+}
 /** Does a ref resolve to a commit in this repo? Lets `--base` fail LOUDLY on an
  *  unfetched/typo'd ref instead of silently diffing against nothing (a vacuous
  *  CI pass), since the diff helpers below swallow git errors to "". */
@@ -408,6 +416,28 @@ export function stagedDiff(cwd, maxBytes = 60_000) {
     const out = gitSafe(["diff", "--cached", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
     return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
 }
+/** Unified diff of the complete local working tree vs HEAD. Git's normal diff
+ * includes both staged and unstaged tracked edits; untracked text files are
+ * appended as synthetic additions so guards can also see their added symbols.
+ * Binary/unreadable files remain in workingFiles (scope checks still apply) but
+ * intentionally contribute no synthetic content to regression analysis. */
+export function workingDiff(cwd, maxBytes = 60_000) {
+    let out = gitSafe(["diff", "HEAD", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
+    const tracked = new Set(gitSafe(["diff", "HEAD", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean));
+    const untracked = gitSafe(["ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter((f) => f && !tracked.has(f));
+    for (const file of untracked) {
+        try {
+            const text = readFileSync(join(cwd, file), "utf8");
+            if (text.includes("\0"))
+                continue;
+            const lines = text.split("\n");
+            const add = lines.map((line) => `+${line}`).join("\n");
+            out += `${out ? "\n" : ""}diff --git a/${file} b/${file}\nnew file mode 100644\n--- /dev/null\n+++ b/${file}\n@@ -0,0 +1,${lines.length} @@\n${add}\n`;
+        }
+        catch { /* unreadable / directory / binary: scope-only is still safe */ }
+    }
+    return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
+}
 /** Resolve a time-travel ref (commit / tag / branch / HEAD~n) to the ISO author-
  *  date of that commit — the instant valid-time windows are filtered against.
  *  Undefined if it can't be resolved (not a git repo, or an unknown ref). Single

package/dist/integrations/hooks.js

@@ -20,6 +20,10 @@ function block(invocation, opts = {}) {
         MARK,
         'if [ -z "$HUNCH_SYNC" ]; then',
         "  export HUNCH_SYNC=1",
+        // A split-private capture must not make a storage-private promise and then
+        // ship the commit diff to a subscription CLI. Shared overlays are a separate
+        // team policy, so only the explicit local-only mode forces deterministic.
+        ...(opts.localOnly ? ["  export HUNCH_SYNTH_PROVIDER=deterministic"] : []),
         `  ( ${invocation} sync --from-hook --quiet${priv}${commit} >/dev/null 2>&1 || true ) &`,
         "fi",
         ENDMARK,