@davesheffer/hunch 1.10.8 → 1.12.0

package/dist/cli/index.js

@@ -57,7 +57,7 @@ import { blockingInScope, vetoInScope, proposedEditLines } from "../core/hookpol
 import { isHumanConfirmed } from "../core/strictgate.js";
 import { appendEvent, readEvents } from "../core/events.js";
 import { computeStats, formatStats } from "../core/stats.js";
-import { injectionMode } from "../core/hookcache.js";
+import { injectionMode, resetSessionInjections } 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, isAcceptedDuplicateAnchor } from "../core/dupdetect.js";
@@ -3797,7 +3797,53 @@ program
             emitContext(provider, "UserPromptSubmit", text);
             return;
         }
+        if (evt.hook_event_name === "PreCompact") {
+            // Compaction is about to summarize injected grounding out of the agent's
+            // context while the dedup map still says "delivered". Reset it so every
+            // post-compact injection is full again. Emit nothing — this event has no
+            // context channel worth spending.
+            resetSessionInjections(evt.session_id);
+            return;
+        }
+        if (evt.hook_event_name === "SubagentStart") {
+            // A delegated agent starts with NONE of the parent session's grounding:
+            // session orientation never fired inside it and only per-edit PreToolUse
+            // follows it in — so read-only agents (Explore/Plan) could work fully
+            // blind. Give it the invariants that must survive delegation. Public
+            // store only; once per agent type per session.
+            const s = new HunchStore(paths);
+            try {
+                const sevRank = { blocking: 0, warning: 1, advisory: 2 };
+                const constraints = s.advisoryRecs("constraints")
+                    .filter((c) => c.status === "active")
+                    .sort((a, b) => sevRank[a.severity] - sevRank[b.severity]);
+                if (!constraints.length)
+                    return;
+                const L = [`🧠 Hunch — delegated agent grounding: ${constraints.length} invariant(s) in force in this repo.`];
+                for (const c of constraints.slice(0, 8)) {
+                    const flat = c.statement.replace(/\s+/g, " ").trim();
+                    const claim = flat.length > 140 ? `${flat.slice(0, 139).trimEnd()}…` : flat;
+                    L.push(`- [${c.severity}] ${claim}${c.scope.length ? ` (scope: ${c.scope.slice(0, 3).join(", ")})` : ""}`);
+                }
+                if (constraints.length > 8)
+                    L.push(`…and ${constraints.length - 8} more — hunch_check_constraints(scope) for your files.`);
+                L.push("Before editing: hunch_check_constraints(scope) · hunch_why(target). Orient: hunch_context(task).");
+                // No dedup here: the hook event carries the PARENT session id, but each
+                // spawned agent is a fresh empty context — deduping would ground the
+                // first Explore and silently starve every later one.
+                emitContext(provider, "SubagentStart", L.join("\n"));
+            }
+            finally {
+                s.close();
+            }
+            return;
+        }
         if (evt.hook_event_name === "SessionStart") {
+            // A compact-resume means everything injected so far was just summarized
+            // away — the dedup map must forget it delivered anything, or the rest of
+            // the session gets delta one-liners against grounding that is gone.
+            if (evt.source === "compact")
+                resetSessionInjections(evt.session_id);
             // Orientation at the moment it matters: what just happened + what's next,
             // straight from the graph — the agent sits down already knowing where it
             // is instead of pulling (or worse, grepping) for it. Cheap reads only

package/dist/core/agenthook.js

@@ -77,6 +77,8 @@ function eventName(value, provider) {
         posttooluse: "PostToolUse",
         userpromptsubmit: "UserPromptSubmit",
         sessionstart: "SessionStart",
+        subagentstart: "SubagentStart",
+        precompact: "PreCompact",
         stop: "Stop",
     };
     if (map[name])
@@ -155,6 +157,8 @@ export function normalizeHookEvent(raw, provider) {
         tool_name: hunchToolName(stringAt(input, "tool_name", "toolName"), toolInput ?? {}),
         tool_input: toolInput,
         prompt: stringAt(input, "prompt", "user_prompt", "userPrompt"),
+        source: stringAt(input, "source"),
+        agent_type: stringAt(input, "agent_type", "agentType", "subagent_type", "subagentType"),
     };
 }
 /** Provider-aware hook output. Context output is intentionally omitted for

package/dist/core/correction.js

@@ -88,6 +88,19 @@ export function buildCorrectionConstraint(input, now) {
     let severity = input.severity ?? "warning";
     if (severity === "blocking" && repoWide && !input.applies_to_all)
         severity = "warning";
+    // AUTHORSHIP TIER. This function hardcoded provenance human_confirmed @1, and
+    // isStrictBlocker treats human_confirmed + blocking as a DENY — so an un-interviewed
+    // agent call could mint a repo-wide deny carrying a signature nobody gave. That made
+    // the highest-authority write path the least gated one, and strictly worse than
+    // hunch_record_decision, which only ever produced advisory memory and is now tiered.
+    //
+    // The token sets the TIER, never whether the write lands. An un-vouched correction is
+    // still recorded immediately and still held against every assistant at edit time and
+    // in CI — Never Twice keeps its promise. What waits for a countersign is only the
+    // authority to DENY.
+    const vouched = input.vouched !== false;
+    if (!vouched && severity === "blocking")
+        severity = "warning";
     return {
         id: constraintId(rule),
         type: input.type ?? "correctness",
@@ -101,13 +114,21 @@ export function buildCorrectionConstraint(input, now) {
         // rule that goes stale. Validated against the repo's real deps when supplied → never mints a
         // never-firing rule for a non-dependency. null when nothing derivable → falls back to scope.
         forbids: deriveForbids(rule, input.knownDeps),
-        rationale: input.rationale ?? "Captured from a human correction of the agent (Never Twice).",
+        rationale: input.rationale ?? (vouched
+            ? "Captured from a human correction of the agent (Never Twice)."
+            : "Recorded by the agent as a correction, WITHOUT a capture interview — advisory testimony until a human countersigns it via /capture (Never Twice)."),
         source_decision: input.source_decision ?? null,
         violations: [],
         status: "active",
         valid_from: now,
         valid_to: null,
-        provenance: { source: "human_confirmed", confidence: 1, evidence: [], last_verified: now },
+        // The signature is EARNED, not assumed. isStrictBlocker treats human_confirmed as
+        // authority to deny, so stamping it on an un-interviewed write forges the one thing
+        // the strict gate trusts. agent_recorded is the same tier hunch_record_decision uses
+        // for an un-token'd write — advisory, real, and honest about who wrote it.
+        provenance: vouched
+            ? { source: "human_confirmed", confidence: 1, evidence: [], last_verified: now }
+            : { source: "agent_recorded", confidence: 0.75, evidence: [], last_verified: now },
     };
 }
 //# sourceMappingURL=correction.js.map

package/dist/core/docanchors.js

@@ -1,12 +1,45 @@
 import { currentForTopic, rejectedForTopic } from "./topics.js";
 const MARKER = /<!--\s*hunch:topic\s+([A-Za-z0-9._/-]+)(?:\s+(dec_[A-Za-z0-9]+))?\s*-->/g;
-/** Parse every hunch:topic marker out of a markdown document. */
+/** Character ranges covered by fenced code blocks (``` or ~~~), so a
+ *  documentation EXAMPLE of a marker never registers as a live anchor.
+ *  CommonMark-lite: a fence of N chars (≤3 leading spaces) closes only on a
+ *  line of ≥N of the same char and nothing else; an unclosed fence runs to
+ *  EOF; a backtick fence's info string may not itself contain a backtick. */
+function fencedRanges(text) {
+    const ranges = [];
+    let open = null;
+    let offset = 0;
+    for (const line of text.split("\n")) {
+        const m = /^ {0,3}(`{3,}|~{3,})(.*)$/.exec(line);
+        if (m) {
+            const ch = m[1][0];
+            if (!open) {
+                if (!(ch === "`" && m[2].includes("`")))
+                    open = { ch, len: m[1].length, start: offset };
+            }
+            else if (ch === open.ch && m[1].length >= open.len && m[2].trim() === "") {
+                ranges.push([open.start, offset + line.length]);
+                open = null;
+            }
+        }
+        offset += line.length + 1;
+    }
+    if (open)
+        ranges.push([open.start, text.length]);
+    return ranges;
+}
+/** Parse every hunch:topic marker out of a markdown document. Markers inside
+ *  fenced code blocks are examples, not declarations, and are skipped. */
 export function parseDocAnchors(text) {
     const out = [];
+    const fences = fencedRanges(text);
     MARKER.lastIndex = 0;
     let m;
     while ((m = MARKER.exec(text))) {
-        out.push({ topic: m[1], pin: m[2] ?? null, line: text.slice(0, m.index).split("\n").length });
+        const at = m.index;
+        if (fences.some(([s, e]) => at >= s && at <= e))
+            continue;
+        out.push({ topic: m[1], pin: m[2] ?? null, line: text.slice(0, at).split("\n").length });
     }
     return out;
 }

package/dist/core/hookcache.js

@@ -55,6 +55,22 @@ export function injectionMode(sessionId, key, content) {
         return "full"; // grounded beats deduped, always
     }
 }
+/** Forget everything injected into a session. Compaction summarizes injected
+ *  grounding out of the agent's context while the dedup map still says
+ *  "delivered" — so on PreCompact / SessionStart[source=compact] the map must
+ *  reset, or post-compact edits get delta one-liners against grounding the
+ *  agent no longer has. Never throws (same posture as injectionMode). */
+export function resetSessionInjections(sessionId) {
+    try {
+        if (!sessionId)
+            return;
+        const file = join(tmpdir(), "hunch-hookcache", `${sessionId.replace(/[^A-Za-z0-9_-]/g, "_").slice(0, 80)}.json`);
+        rmSync(file, { force: true });
+    }
+    catch {
+        /* unwritable tmpdir — next injectionMode call falls back to "full" anyway */
+    }
+}
 /** Drop session caches from long-gone sessions (best effort, bounded dir). */
 function sweep(dir) {
     try {

package/dist/core/premises.js

@@ -5,7 +5,7 @@ const clip = (s, n = 90) => (s.length > n ? s.slice(0, n - 1).trimEnd() + "…"
 function validRel(p) {
     return !!p && !p.startsWith("/") && !/^[A-Za-z]:[\\/]/.test(p) && !p.split(/[\\/]/).includes("..");
 }
-function checkPath(claim, rel, wantExists, env) {
+function checkPath(claim, rel, wantExists, env, under) {
     if (!validRel(rel)) {
         return { claim, holds: false, reason: `unevaluable: path must be repo-relative ("${rel}") — fix the premise record` };
     }
@@ -15,9 +15,26 @@ function checkPath(claim, rel, wantExists, env) {
             ? { claim, holds: true, reason: `"${rel}" still exists` }
             : { claim, holds: false, reason: `"${rel}" no longer exists` };
     }
+    // NEGATIVE probe. A missing path proves nothing on its own: a deleted subtree, a
+    // renamed directory and a typo all read as "absent". The `under` anchor is what makes
+    // the answer mean something — when the ancestor is gone, the question no longer has a
+    // subject, so the premise is UNEVALUABLE rather than quietly satisfied. That is the
+    // decay this closes: it is what rotted five decisions pointing into vscode-extension/
+    // after that tree was cut.
+    if (under !== undefined) {
+        if (!validRel(under)) {
+            return { claim, holds: false, reason: `unevaluable: under must be repo-relative ("${under}") — fix the premise record` };
+        }
+        if (!env.exists(under)) {
+            return { claim, holds: false, reason: `unevaluable: the anchor "${under}" no longer exists, so "${rel}" being absent proves nothing — re-anchor or supersede` };
+        }
+    }
     return exists
         ? { claim, holds: false, reason: `"${rel}" now exists` }
-        : { claim, holds: true, reason: `"${rel}" still absent` };
+        // The residual risk is stated, not hidden: a MISTYPED path is also absent, and it
+        // stays absent forever — the harm is a premise that silently never fires, which no
+        // existence probe can detect. Saying so is what keeps "holds" honest.
+        : { claim, holds: true, reason: `"${rel}" still absent${under ? ` under "${under}"` : ""} (a mistyped path also reads as absent — confirm it on re-attest)` };
 }
 function checkOne(p, env) {
     // The clock is an INJECTED input, so it is an unevaluable case like any other.
@@ -30,7 +47,7 @@ function checkOne(p, env) {
         return { claim: p.claim, holds: false, reason: `unevaluable: caller supplied a non-ISO clock ("${env.now}")` };
     }
     if (p.path_absent !== undefined)
-        return checkPath(p.claim, p.path_absent, false, env);
+        return checkPath(p.claim, p.path_absent, false, env, p.under);
     if (p.path_exists !== undefined)
         return checkPath(p.claim, p.path_exists, true, env);
     if (p.review_by !== undefined) {

package/dist/core/types.js

@@ -115,12 +115,29 @@ export const ConformancePredicateSchema = z.object({
 // (the human renews, supersedes, or retires — same ethos as topic anchors).
 export const PremiseSchema = z.object({
     claim: z.string().min(1).describe("the human-readable reason this decision rests on"),
-    path_absent: z.string().optional().describe("premise holds while this repo-relative path does NOT exist"),
+    path_absent: z.string().optional().describe("premise holds while this repo-relative path does NOT exist. Requires `under`. PREFER path_exists where you can: a negative probe cannot tell 'verified absent' from 'wrong path', so it fails OPEN, while path_exists fails closed."),
+    under: z.string().optional().describe("required with path_absent: an EXISTING repo-relative ancestor of it. When this anchor disappears (a directory deleted or moved), the premise reads unevaluable instead of silently 'still absent'."),
     path_exists: z.string().optional().describe("premise holds while this repo-relative path exists"),
     review_by: z.string().optional().describe("dated attestation: premise holds until this ISO date, then needs re-attesting"),
     attested: z.string().optional().describe("ISO date a human last attested the claim (informational)"),
 }).refine((p) => [p.path_absent, p.path_exists, p.review_by].filter((x) => x !== undefined).length <= 1, {
     message: "a premise carries at most one check (path_absent | path_exists | review_by)",
+}).refine((p) => p.path_absent === undefined || (typeof p.under === "string" && p.under.trim().length > 0), {
+    message: "path_absent requires `under`: an existing ancestor path. Without an anchor, a deleted or renamed subtree reads as 'still absent' forever. Prefer path_exists where you can — it fails closed.",
+    path: ["under"],
+}).refine((p) => {
+    if (p.path_absent === undefined || typeof p.under !== "string")
+        return true;
+    const norm = (s) => s.replace(/\\/g, "/").replace(/^\.\//, "").replace(/\/+$/, "");
+    const target = norm(p.path_absent);
+    const anchor = norm(p.under);
+    // Must be a real ANCESTOR, not an arbitrary existing path: `under` is what makes
+    // "absent" meaningful ("nothing named gateway UNDER src"). An unrelated anchor
+    // would prove the premise still evaluable while telling you nothing about it.
+    return anchor !== "" && target !== anchor && target.startsWith(`${anchor}/`);
+}, {
+    message: "`under` must be a proper ancestor of `path_absent` (e.g. path_absent 'src/gateway' with under 'src')",
+    path: ["under"],
 });
 export const DecisionSchema = z.object({
     id: z.string().describe("dec_*"),

package/dist/integrations/scaffold.js

@@ -156,6 +156,18 @@ export function installClaudeHooks(root, hookCmd) {
         ...keep(json.hooks.SessionStart),
         { hooks: [{ type: "command", command: hookCmd }] },
     ];
+    // Delegated agents start with no session grounding (orientation never fired
+    // inside them); compaction summarizes injected grounding away while the dedup
+    // map still says "delivered". These two events keep delivery alive across the
+    // whole session lifecycle, not just its first context window.
+    json.hooks.SubagentStart = [
+        ...keep(json.hooks.SubagentStart),
+        { hooks: [{ type: "command", command: hookCmd }] },
+    ];
+    json.hooks.PreCompact = [
+        ...keep(json.hooks.PreCompact),
+        { hooks: [{ type: "command", command: hookCmd }] },
+    ];
     // Verification pipeline (core/pipeline.ts): PostToolUse records observable
     // facts (edits, verify commands); Stop refuses to end a turn with unverified
     // product edits at firm/strict firmness. Delivery is enforced, not hoped for.

package/dist/mcp/server.js

@@ -739,7 +739,8 @@ export function buildServerWithRootControl(initialRoot) {
                 // PremiseSchema in src/core/types.ts.
                 premises: z.array(z.object({
                     claim: z.string().min(1).describe("the human-readable reason this decision rests on"),
-                    path_absent: z.string().optional().describe("premise holds while this repo-relative path does NOT exist"),
+                    path_absent: z.string().optional().describe("premise holds while this repo-relative path does NOT exist. REQUIRES `under`. Prefer path_exists where you can — a negative probe fails OPEN, a positive one fails closed."),
+                    under: z.string().optional().describe("required with path_absent: an EXISTING repo-relative ANCESTOR of it (path_absent 'src/gateway' -> under 'src'). When the anchor disappears the premise reads unevaluable instead of silently 'still absent'."),
                     path_exists: z.string().optional().describe("premise holds while this repo-relative path exists"),
                     review_by: z.string().optional().describe("dated attestation: premise holds until this ISO date, then needs re-attesting"),
                     attested: z.string().optional().describe("ISO date a human last attested the claim (informational)"),
@@ -941,6 +942,7 @@ export function buildServerWithRootControl(initialRoot) {
             rationale: z.string().optional().describe("Why it must hold."),
             source_decision: z.string().optional().describe("id of a decision this correction derives from."),
             private: z.boolean().optional().describe("write into the PRIVATE overlay store (HUNCH_PRIVATE_DIR) instead of the committed repo — a sensitive rule enforced locally (pre-edit hook + local check) but never exposed in a public PR comment. Errors if no private store is configured."),
+            capture_token: z.string().optional().describe("token from hunch_capture_decision. The rule is recorded and enforced either way — the token only decides whether it may DENY: without one it lands as advisory testimony capped at severity 'warning'."),
         },
     }, async (input) => {
         try {
@@ -950,7 +952,12 @@ export function buildServerWithRootControl(initialRoot) {
             // paths (edit-tool payloads and MCP roots are absolute) and every consumer matches
             // repo-relative — without this the rule would be blocking-but-inert and would leak
             // the local filesystem path into the committed graph.
-            const rec = buildCorrectionConstraint({ ...input, knownDeps: knownRepoDeps(root), root }, new Date().toISOString());
+            // Same authorship tier as hunch_record_decision: a consumed token mints the
+            // signature, an un-token'd write is testimony. Here the stakes are HIGHER — a
+            // blocking constraint DENIES edits, so an un-vouched write is capped at
+            // "warning" rather than being refused. Never Twice still lands immediately.
+            const vouched = consumeCaptureToken(input.capture_token);
+            const rec = buildCorrectionConstraint({ ...input, knownDeps: knownRepoDeps(root), root, vouched }, new Date().toISOString());
             // Private corrections go to the overlay (enforced locally via the merged read,
             // never rendered into the public CI comment, which is public-only by construction).
             const home = store.captureHome(!!input.private);
@@ -983,7 +990,14 @@ export function buildServerWithRootControl(initialRoot) {
             // The Constraint itself is the durable retry queue. Normal `hunch index`
             // and post-commit sync rescan it; no in-process timer can be lost on exit.
             const reviewNote = "\n\nREVIEW PENDING: After the fix is committed, run hunch index; an installed post-commit hook retries this automatically on the fixing commit. Only the supported static ESM import-declaration package projection is eligible, and it remains activation-blocked; the immediate guard is already durable.";
-            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where} It now ${enforce}.${reviewNote}`);
+            // Say plainly which tier this landed in. A silent downgrade would be its own
+            // dishonesty: the caller asked for "blocking" and must be told it is not.
+            const tierNote = vouched
+                ? ""
+                : `
+
+⚠ Recorded WITHOUT a capture interview — this rule is agent_recorded TESTIMONY${input.severity === "blocking" ? ' and was capped from "blocking" to "warning"' : ""}. It IS enforced: the pre-edit hook and CI surface it on every matching edit from now on. What it cannot do is DENY an edit — only a rule a human countersigned may block. Countersign it by re-recording through hunch_capture_decision → hunch_record_correction(capture_token).`;
+            return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where} It now ${enforce}.${reviewNote}${tierNote}`);
         }
         catch (e) {
             return err(`Failed to record correction: ${e.message}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.10.8",
+  "version": "1.12.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -1,19 +1,19 @@
 {
-  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-29/server.schema.json",
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
   "name": "io.github.davesheffer/hunch",
-  "description": "Engineering memory for AI-assisted codebases: decisions, rejected alternatives, bug lineage, and deterministic architectural gates, served git-natively over MCP.",
+  "description": "Engineering memory for AI-assisted codebases: decisions, bug lineage and invariants, over MCP.",
   "repository": {
     "url": "https://github.com/davesheffer/hunch",
     "source": "github"
   },
   "websiteUrl": "https://hunch-pi.vercel.app",
-  "version": "1.10.8",
+  "version": "1.12.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.10.8",
+      "version": "1.12.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {