@davesheffer/hunch 1.47.0 → 1.47.2

package/dist/cli/index.js

@@ -23,7 +23,8 @@ import { Command } from "commander";
 import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget, isDir, realpathNorm, repoRelativeTarget } from "../core/paths.js";
 import { writeFileAtomic } from "../core/io.js";
 import { boundedSpawnSync } from "../core/boundedSpawn.js";
-import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
+import { looksLikeCorrection, CORRECTION_NUDGE, stripHostBlocks } from "../core/correction.js";
+import { roleHasHunchTools } from "../core/subagentrole.js";
 import { HUNCH_VERSION } from "../core/version.js";
 import { registerIntegrationCommands } from "./integrations.js";
 import { registerTaskReportCommands } from "./taskReport.js";
@@ -46,7 +47,7 @@ import { isParserLoadError, loadNativeTreeSitter } from "../extractors/nativeTre
 import { syncCommit, recordFailure, captureTestRun } from "../synthesis/synthesize.js";
 import { parseTestReport } from "../extractors/testreport.js";
 import { readSynthesisPreference, resolveSynthesisProvider, selectProvider, SYNTH_PREFERENCES, writeSynthesisPreference, normalizeProviderName, } from "../synthesis/provider.js";
-import { isGitRepo, isGitRepoRoot, sameGitPublication, sameRemoteUrl, canonicalRemoteUrl, repositoryUsesRemote, headSha, isolatedHeadSha, logSince, lastChangeDate, checkFreshnessRevision, teamPullIsFresh, firstCommitForFile, stagedFiles, workingFiles, commitFiles, asOfDate, stagedGateDiff, workingGateDiff, commitGateDiff, rangeFiles, rangeGateDiff, rangeCommits, revExists, revParse, commitAndPushHunch, pullHunchStatus, pullHunchStatusDetailed, describePullFailure, syncExistingHunch, gitUntrackCached, gitCommonDir, checkoutCommonDir, separateGitDirCandidate, separateGitDirLink, hooksDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges, commitRepairStatusAgainst, commitPatchIds, mergeRangeChanges, commitsExist } from "../extractors/git.js";
+import { isGitRepo, isGitRepoRoot, sameGitPublication, sameRemoteUrl, canonicalRemoteUrl, repositoryUsesRemote, headSha, isolatedHeadSha, logSince, lastChangeDate, checkFreshnessRevision, teamPullIsFresh, firstCommitForFile, stagedFiles, workingFiles, commitFiles, asOfDate, stagedGateDiff, workingGateDiff, commitGateDiff, rangeFiles, rangeGateDiff, rangeCommits, revExists, revParse, sameFilesystemEntry, commitAndPushHunch, pullHunchStatus, pullHunchStatusDetailed, describePullFailure, syncExistingHunch, gitUntrackCached, gitCommonDir, checkoutCommonDir, separateGitDirCandidate, separateGitDirLink, hooksDir, isLinkedWorktree, mainWorktreeRoot, gitMemoryLog, memoryMoveDiff, revertMemoryMove, pushCurrentBranch, commitChanges, commitRepairStatusAgainst, commitPatchIds, mergeRangeChanges, commitsExist } from "../extractors/git.js";
 import { runbookDraft } from "../core/runbookDraft.js";
 import { parseMemoryLog } from "../core/memorylog.js";
 import { renamesOf, planRepair, repairDecision, repairConstraint } from "../core/repair.js";
@@ -61,7 +62,7 @@ import { renderText, renderMarkdown, renderSarif, renderImpact, reportFailsStric
 import { partitionReview, isReviewDraft, READY_MIN_GROUNDED } from "../core/reviewqueue.js";
 import { installPostCommitHook, installPreCommitHook, installPostMergeHook, installPostCheckoutHook, hookStatus, hookReport, hookInvocationLines, formatHookInstall, sharedHooksNote } from "../integrations/hooks.js";
 import { ensureSharedOverlayPointer } from "../integrations/worktree.js";
-import { flushCapture, flushMemoryHome, flushMemoryHomes, pinSharedRemote, sharedRemoteFor } from "../integrations/sync.js";
+import { flushCapture, flushMemoryHome, flushMemoryHomes, pinSharedRemote, sharedRemoteFor, holdsOnDefaultBranch, HELD_ON_DEFAULT_BRANCH } from "../integrations/sync.js";
 import { installMergeDriver } from "../integrations/mergeDriver.js";
 import { ensureGitignore, ignoreHunchMemory, HUNCH_MEMORY_DIRS, upgradeManagedGitignore, describeGitignoreUpgrade, memoryIgnoreRule, describeMemoryIgnoreRule } from "../integrations/gitignore.js";
 import { writeCiWorkflow } from "../integrations/ciAction.js";
@@ -210,7 +211,7 @@ registerReviewMemoryCommands(program, (records, repository, privateOnly) => {
     for (const record of records)
         store.putCapture("constraints", record, privateOnly);
     store.reindex();
-    if (home === "public" && !store.autoCommit)
+    if (home === "public" && !publicFlushCommitsGrounding(store, root))
         refreshExistingGrounding(root, store);
     pumpMemoryHome(store, root, home, `hunch: capture ${records.length} sourced review rule(s)`);
 }, (repository, privateOnly) => {
@@ -447,8 +448,25 @@ function storeFor(opts = {}) {
     const { store, teamPullStatus, teamPullDetail } = openTeamStore(root, opts);
     return { store, root, teamPullStatus, teamPullDetail };
 }
+/** Whether a public memory flush commits the tracked grounding docs itself. When it
+ *  won't (auto-commit off, or held on the default branch), a by-hand command refreshes
+ *  them on disk instead, so CLAUDE.md never keeps enforcing what the command just changed. */
+function publicFlushCommitsGrounding(store, root) {
+    return store.autoCommit && !holdsOnDefaultBranch(hunchPaths(root).hunch);
+}
+// A held public flush says so once per command, on stderr: stdout may be a --json payload.
+let heldNoticePrinted = false;
+function noteHeld() {
+    if (heldNoticePrinted)
+        return;
+    heldNoticePrinted = true;
+    console.error(`  ↳ ${HELD_ON_DEFAULT_BRANCH}`);
+}
 function pumpMemoryHome(store, root, home, message) {
-    flushMemoryHome(store, hunchPaths(root).hunch, home, message);
+    const flush = flushMemoryHome(store, hunchPaths(root).hunch, home, message);
+    if (flush === "held")
+        noteHeld();
+    return flush;
 }
 function pumpPolicyHome(store, root, service, policyId, message) {
     const home = service.repository.homeOfPolicy(policyId);
@@ -457,7 +475,9 @@ function pumpPolicyHome(store, root, service, policyId, message) {
     pumpMemoryHome(store, root, home, message);
 }
 function pumpMemoryHomes(store, root, homes, message) {
-    flushMemoryHomes(store, hunchPaths(root).hunch, homes, message);
+    const flushes = flushMemoryHomes(store, hunchPaths(root).hunch, homes, message);
+    if (flushes.public === "held")
+        noteHeld();
 }
 // ---- init -----------------------------------------------------------------
 program
@@ -767,7 +787,7 @@ program
     // while the docs are still Git-clean so it can stage them atomically with
     // the graph. Pre-refreshing would make the safety filter treat generated
     // docs as user-dirty and leave them stranded outside the memory commit.
-    const healed = shouldAutoCommit ? [] : refreshExistingGrounding(root, store);
+    const healed = shouldAutoCommit && publicFlushCommitsGrounding(store, root) ? [] : refreshExistingGrounding(root, store);
     console.log(`Indexed ${res.files} files:`);
     console.log(`  ${counts.symbols} symbols, ${counts.edges} edges, ${counts.components} components`);
     for (const item of res.coverage) {
@@ -995,7 +1015,13 @@ program
     // each home's artifacts into at most one memory commit.
     const publicCapture = r.status === "written" && !toOverlay;
     const privateCapture = r.status === "written" && toOverlay;
-    const groundingToStage = publicCapture || graphRefreshed || publicRepairTouched ? refreshCommittableGrounding(root, store) : [];
+    const publicNeedsFlush = publicCapture || graphRefreshed || publicRepairTouched;
+    // The default-branch hold covers the post-commit hook too. Its baked-in --commit is
+    // the installed auto-commit default, so only a --commit typed by hand overrides it.
+    // Decided before the grounding refresh: a held capture leaves tracked docs at HEAD,
+    // so `git commit -a` cannot commit counts whose record it leaves untracked.
+    const publicHeld = doCommit && publicNeedsFlush && (opts.fromHook || opts.commit === undefined) && holdsOnDefaultBranch(hunchPaths(root).hunch);
+    const groundingToStage = publicNeedsFlush && !publicHeld ? refreshCommittableGrounding(root, store) : [];
     if (!opts.fromHook && (r.status === "written" || graphRefreshed || publicRepairTouched)) {
         const healed = refreshExistingGrounding(root, store);
         const refreshed = [...new Set([...groundingToStage.map((file) => relative(root, file)), ...healed])];
@@ -1003,9 +1029,10 @@ program
             console.log(`  ↳ grounding refreshed: ${refreshed.join(", ")}`);
     }
     if (doCommit) {
-        const publicNeedsFlush = publicCapture || graphRefreshed || publicRepairTouched;
         const privateNeedsFlush = privateCapture || (privateCorrectionQueued && graphRefreshed) || g2Recorded > 0 || privateRepairTouched;
-        const publicResult = publicNeedsFlush
+        if (publicHeld && !opts.quiet)
+            console.log(`  ↳ ${HELD_ON_DEFAULT_BRANCH}`);
+        const publicResult = publicNeedsFlush && !publicHeld
             ? commitAndPushHunch(hunchPaths(root).hunch, publicCapture
                 ? `hunch: capture ${r.decision?.id ?? "decision"}`
                 : graphRefreshed
@@ -2283,12 +2310,13 @@ program
         }
     }
     store.reindex();
-    if (dec || con)
-        flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: capture ${dec + con} inline intent(s)`);
+    const flush = dec || con ? flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: capture ${dec + con} inline intent(s)`) : null;
     if (!intents.length)
         console.log("No `hunch-why:` / `hunch-rule:` comments found.");
     else
         console.log(`✓ captured ${dec} decision(s) + ${con} constraint(s) from inline comments${opts.private ? " [private overlay]" : ""}`);
+    if (flush === "held")
+        console.log(`  ↳ ${HELD_ON_DEFAULT_BRANCH}`);
     store.close();
 });
 // ---- conform (Architectural Conformance: does the code still satisfy recorded intent) ----
@@ -2330,7 +2358,7 @@ program
             valid_from: now,
         });
         store.reindex();
-        if (home === "public" && !store.autoCommit)
+        if (home === "public" && !publicFlushCommitsGrounding(store, root))
             refreshExistingGrounding(root, store);
         pumpMemoryHome(store, root, home, `hunch: record architectural invariant ${d.id}`);
         console.log(`✓ recorded architectural invariant ${d.id}: "${opts.add}"`);
@@ -4047,7 +4075,7 @@ program
         }
         store.reindex();
         const home = store.captureHome(!!opts.private);
-        if (home === "public" && !store.autoCommit)
+        if (home === "public" && !publicFlushCommitsGrounding(store, root))
             refreshExistingGrounding(root, store);
         const flush = flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: import ${decisions.length} ADR(s) from ${dir}`);
         const live = decisions.filter((d) => d.status === "accepted").length;
@@ -4066,6 +4094,8 @@ program
         }
         if (flush === "pushed")
             console.log("  ↳ private memory committed + pushed");
+        if (flush === "held")
+            console.log(`  ↳ ${HELD_ON_DEFAULT_BRANCH}`);
     }
     finally {
         store.close();
@@ -4203,7 +4233,7 @@ program
     store.reindex();
     // Public grounding is a publishable artifact. Private rules stay local and
     // are surfaced by local checks/MCP, never copied into committed agent docs.
-    if (home === "public" && !store.autoCommit)
+    if (home === "public" && !publicFlushCommitsGrounding(store, root))
         refreshExistingGrounding(root, store);
     const flush = flushCapture(store, hunchPaths(root).hunch, !!opts.private, `hunch: capture ${c.id}`);
     console.log(`✓ recorded ${c.severity} constraint ${c.id}: "${c.statement}" (scope: ${scope.join(", ") || "repo"})${opts.private ? " [private overlay]" : ""}`);
@@ -4217,6 +4247,8 @@ program
     }
     if (flush === "pushed")
         console.log("  ↳ private memory committed + pushed");
+    if (flush === "held")
+        console.log(`  ↳ ${HELD_ON_DEFAULT_BRANCH}`);
     store.close();
 });
 // ---- test (failure-learning loop) -----------------------------------------
@@ -4960,7 +4992,7 @@ program
     // is on, but no commit happens to carry that refresh when it's off, so do it here
     // too — otherwise a retired constraint keeps showing as enforced on disk (the same
     // gap record-constraint and `conform --add` close for their own capture path).
-    if (home === "public" && !store.autoCommit)
+    if (home === "public" && !publicFlushCommitsGrounding(store, root))
         refreshExistingGrounding(root, store);
     // `--reason` goes in the commit BODY, never the subject: `hunch log`'s move
     // classifier (src/core/memorylog.ts) regexes the commit SUBJECT for keywords
@@ -4968,11 +5000,14 @@ program
     // in the subject could accidentally match one and misclassify the move.
     const willCommit = home === "private" ? store.privateAutoCommit : store.autoCommit;
     const message = `hunch: retire constraint ${id}${opts.reason ? `\n\n${opts.reason}` : ""}`;
-    pumpMemoryHome(store, root, home, message);
+    const flush = pumpMemoryHome(store, root, home, message);
     console.log(`✓ ${retired.id} retired — window closed at ${retired.valid_to?.slice(0, 10)}.`);
     if (opts.reason && !willCommit) {
         console.log("  ⚠ --reason is not recorded anywhere: auto-commit is off, so no commit message captured it.");
     }
+    else if (opts.reason && flush === "held") {
+        console.log("  ⚠ --reason is not recorded anywhere: the commit was held on the default branch, so no commit message captured it.");
+    }
     store.close();
 });
 // ---- firmness (agent-hook enforcement level) ------------------------------
@@ -5198,10 +5233,14 @@ program
         if (!evt)
             return;
         eventName = evt.hook_event_name;
-        const root = findRoot();
+        // Grounding reads the store of the checkout the event's file is in; the prompt's
+        // task and the hook evidence stay with the process root that opened them.
+        const processRoot = findRoot();
+        const routed = hookEventRoot(processRoot, evt);
+        const root = routed.root;
         // The host delivered this event: runtime evidence for `hunch integrations check`,
         // recorded before any policy decision so firmness never hides delivery itself.
-        recordHookObservation(root, provider, evt.hook_event_name, evt.tool_outcome?.status);
+        recordHookObservation(processRoot, provider, evt.hook_event_name, evt.tool_outcome?.status);
         const paths = hunchPaths(root);
         const firmness = readConfig(paths).firmness;
         if (firmness === "off")
@@ -5225,7 +5264,7 @@ program
                         // Same rule as the pre-edit path: strict never grounds from stale team rules.
                         const stale = firmness === "strict" && opened.teamPullStatus && !teamPullIsFresh(opened.teamPullStatus);
                         if (!stale)
-                            shellGround = shellWriteGrounding(root, store, provider, evt, written);
+                            shellGround = shellWriteGrounding(root, store, provider, evt, written, processRoot);
                     }
                 }
                 else {
@@ -5418,9 +5457,11 @@ program
                     return flat.length > max ? `${flat.slice(0, max - 1).trimEnd()}…` : flat;
                 };
                 const type = (evt.agent_type ?? "").toLowerCase();
+                // A role whose tool list leaves out Hunch's MCP tools is not told to call them.
+                const tools = roleHasHunchTools(root, evt.agent_type ?? "");
                 const L = [];
                 const served = [];
-                const route = routedCwd
+                const route = routedCwd && tools
                     ? `Worktree routing: call hunch_context first with cwd: ${JSON.stringify(routedCwd)}, and pass the same cwd to hunch_task, hunch_report, and every Hunch capture/write call in this delegated task.`
                     : null;
                 const activeProvider = provider;
@@ -5440,8 +5481,9 @@ program
                         served.push({ kind: "components", record_id: c.id, token_cost: Math.ceil([...line].length / 4) });
                     }
                     if (components.length > 12)
-                        L.push(`…and ${components.length - 12} more — hunch_structure() for the full map.`);
-                    L.push("Orient: hunch_structure(target) · hunch_why(target) · hunch_context(task).");
+                        L.push(`…and ${components.length - 12} more${tools ? " — hunch_structure() for the full map" : ""}.`);
+                    if (tools)
+                        L.push("Orient: hunch_structure(target) · hunch_why(target) · hunch_context(task).");
                 }
                 else if (/plan|architect|design/.test(type)) {
                     // A plan drafted blind re-proposes what the graph already rejected.
@@ -5458,7 +5500,8 @@ program
                         L.push(line);
                         served.push({ kind: "decisions", record_id: d.id, token_cost: Math.ceil([...line].length / 4) });
                     }
-                    L.push("Before finalizing a plan: hunch_why(target) · hunch_current_decision(topic) · hunch_check_constraints(scope).");
+                    if (tools)
+                        L.push("Before finalizing a plan: hunch_why(target) · hunch_current_decision(topic) · hunch_check_constraints(scope).");
                 }
                 else {
                     const sevRank = { blocking: 0, warning: 1, advisory: 2 };
@@ -5476,8 +5519,9 @@ program
                         served.push({ kind: "constraints", record_id: c.id, token_cost: Math.ceil([...line].length / 4) });
                     }
                     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).");
+                        L.push(`…and ${constraints.length - 8} more${tools ? " — hunch_check_constraints(scope) for your files" : "; the edit hook shows the ones your files touch"}.`);
+                    if (tools)
+                        L.push("Before editing: hunch_check_constraints(scope) · hunch_why(target). Orient: hunch_context(task).");
                 }
                 if (route)
                     L.push(route);
@@ -5582,9 +5626,13 @@ program
             return;
         }
         const targets = editTargets(root, evt.tool_input);
-        // Nothing inside the repo → nothing for Hunch to say.
-        if (!targets.length)
+        // Nothing inside the repo → nothing for Hunch to say, except for a file in a
+        // linked worktree of this repository Hunch could not ground (never silently).
+        if (!targets.length) {
+            if (routed.ungrounded)
+                emitContext(provider, "PreToolUse", routed.ungrounded);
             return;
+        }
         // Grounding below stays about the first in-repo file; the strict gate checks every target.
         const { abs, target } = targets[0];
         // A compiled red→green probe is only meaningful if its red receipt exists
@@ -5646,12 +5694,12 @@ program
                     : `Hunch: this patch is denied for ${denials.length} files (${denials.map((d) => d.target).join(", ")}).\n${denials.map((d) => d.hit.reason).join("\n")}`;
                 emitDeny(provider, reason);
                 for (const d of denials)
-                    observeHookDenial(root, provider, evt, d.target, d.hit);
+                    observeHookDenial(processRoot, provider, evt, d.target, d.hit);
                 return;
             }
         }
         // advisory / firm / strict(non-blocking): inject the relevant Hunch slice.
-        const grounded = fileGrounding(root, store, provider, evt, target, abs);
+        const grounded = fileGrounding(root, store, provider, evt, target, abs, processRoot);
         if (!grounded)
             return; // no noise on files Hunch hasn't learned yet
         emitContext(provider, "PreToolUse", grounded.text, grounded.mode === "full" ? grounded.recalled ?? undefined : undefined);
@@ -5830,7 +5878,7 @@ program
             store.reindex();
             if (home === "public") {
                 publicGroundingChanged = true;
-                if (!store.autoCommit)
+                if (!publicFlushCommitsGrounding(store, root))
                     refreshExistingGrounding(root, store);
             }
             console.log(opts.approveImport
@@ -5890,7 +5938,7 @@ program
         store.reindex();
         if (home === "public") {
             publicGroundingChanged = true;
-            if (!store.autoCommit)
+            if (!publicFlushCommitsGrounding(store, root))
                 refreshExistingGrounding(root, store);
         }
     }
@@ -5909,7 +5957,7 @@ program
         store.reindex();
         if (home === "public") {
             publicGroundingChanged = true;
-            if (!store.autoCommit)
+            if (!publicFlushCommitsGrounding(store, root))
                 refreshExistingGrounding(root, store);
         }
         console.log(`✓ accepted ${opts.accept} (now ${source}, confidence 0.95${armed ? `, ${armed} tripwire(s) now blocking` : ""})`);
@@ -5968,7 +6016,7 @@ program
                 armedTotal += accepted.armed;
             }
             store.reindex();
-            if (publicGroundingChanged && !store.autoCommit)
+            if (publicGroundingChanged && !publicFlushCommitsGrounding(store, root))
                 refreshExistingGrounding(root, store);
             console.log(`✓ accepted ${ready.length} verified draft(s); ${armedTotal} tripwire(s) now blocking.`);
             for (const it of ready)
@@ -6128,7 +6176,7 @@ program
         }
         if (accepted || rejected) {
             store.reindex();
-            if (publicAccepted && !store.autoCommit)
+            if (publicAccepted && !publicFlushCommitsGrounding(store, root))
                 refreshExistingGrounding(root, store);
             pumpMemoryHomes(store, root, touchedHomes, "hunch: auto-review decision lifecycle");
         }
@@ -7599,15 +7647,64 @@ function toRepoRel(root, abs) {
         return "";
     return rel;
 }
+/** The repository root a hook event belongs to. Normally the process root, but an
+ *  edit to a file in another LINKED worktree of the same repository (or a subagent
+ *  started in one) belongs to that worktree's memory: grounded against the process
+ *  root it was dropped as "outside the repo", with no output at all. Re-roots only
+ *  to a worktree sharing this repository's git common dir that carries its own
+ *  .hunch/; one without it is reported as ungrounded rather than skipped silently.
+ *  Checkouts are told apart by their `.git` entry, never by a .hunch/ hit, so a
+ *  nested package .hunch/ inside this checkout (a monorepo) never displaces the
+ *  process root and its blocking constraints. Git is spawned only for a file in a
+ *  different checkout than the process root's. */
+function hookEventRoot(processRoot, evt) {
+    const toolEvent = evt.hook_event_name === "PreToolUse" || evt.hook_event_name === "PostToolUse" || evt.hook_event_name === "PostToolUseFailure";
+    const subject = evt.hook_event_name === "SubagentStart" ? evt.cwd
+        : toolEvent ? (evt.tool_input?.patch_files?.[0]?.path ?? evt.tool_input?.file_path) : undefined;
+    if (!subject || !isAbsolute(subject))
+        return { root: processRoot };
+    try {
+        const ownerTop = checkoutTop(evt.hook_event_name === "SubagentStart" ? subject : dirname(subject));
+        const processTop = checkoutTop(processRoot);
+        if (!ownerTop || !processTop || sameFilesystemEntry(ownerTop, processTop))
+            return { root: processRoot };
+        const common = checkoutCommonDir(processRoot);
+        const ownerCommon = common ? checkoutCommonDir(ownerTop) : "";
+        if (!common || !ownerCommon || !sameFilesystemEntry(common, ownerCommon))
+            return { root: processRoot };
+        // The same Hunch root inside the other worktree: its top, or the package dir a
+        // subdirectory-rooted process uses.
+        const owner = join(ownerTop, relative(processTop, processRoot));
+        if (isDir(join(owner, ".hunch")))
+            return { root: owner };
+        return { root: processRoot, ungrounded: `Hunch: ${toPosixTarget(subject)} is in linked worktree ${toPosixTarget(ownerTop)}, which has no .hunch/ — this edit proceeds ungrounded.` };
+    }
+    catch {
+        return { root: processRoot };
+    }
+}
+/** The nearest directory at or above `start` holding a `.git` entry (a checkout's top;
+ *  a linked worktree's `.git` is a file), or "" outside every checkout. Pure fs. */
+function checkoutTop(start) {
+    let cur = resolve(start);
+    for (;;) {
+        if (existsSync(join(cur, ".git")))
+            return cur;
+        const parent = dirname(cur);
+        if (parent === cur)
+            return "";
+        cur = parent;
+    }
+}
 /** Files a shell command wrote get the grounding the edit tools would have
  *  delivered before the edit — late, but while the agent can still revise.
  *  Already-served grounding (a delta) is not repeated. */
 const MAX_SHELL_GROUNDED = 3;
-function shellWriteGrounding(root, store, provider, evt, written) {
+function shellWriteGrounding(root, store, provider, evt, written, ledgerRoot = root) {
     const parts = [];
     const grounded = [];
     for (const target of written.slice(0, MAX_SHELL_GROUNDED)) {
-        const g = fileGrounding(root, store, provider, evt, target, join(root, target));
+        const g = fileGrounding(root, store, provider, evt, target, join(root, target), ledgerRoot);
         if (g?.mode === "full") {
             parts.push(g.text);
             grounded.push(target);
@@ -7677,19 +7774,21 @@ function promptTaskSelection(root, store, provider, evt) {
     const taskId = hookReportTaskId(root, provider, evt);
     if (!taskId)
         return "";
+    // Host-injected blocks (reminders, browser instructions) are not the task the human named.
+    const humanText = stripHostBlocks(evt.prompt ?? "");
     const selection = selectForTask(liveSelectionRecords({
         decisions: store.recs("decisions"),
         bugs: store.recs("bugs"),
         constraints: store.recs("constraints"),
         findings: store.recs("findings"),
-    }), evt.prompt ?? "", { root, pathExists: (p) => existsSync(join(root, p)) });
+    }), humanText, { root, pathExists: (p) => existsSync(join(root, p)) });
     // Same task id again (a notification alias) keeps its own earlier selection; a
     // new task that CONTINUES the session's previous one inherits that task's
     // selection only on a bare follow-up ("continue", "go on"), so it is not left
     // ungrounded. A substantive prompt names its own task: a same-session prompt
     // inside the continuation window must not hide memory behind an old selection.
     let previous = loadTaskSelection(taskId);
-    if (!previous && isBareFollowUp(evt.prompt ?? "")) {
+    if (!previous && isBareFollowUp(humanText)) {
         try {
             const continues = readTaskReport(root, taskId).task.continues;
             previous = continues ? loadTaskSelection(continues) : null;
@@ -7726,8 +7825,9 @@ const SIBLING_MEMORY_BUDGET_TOKENS = 800;
  *  retired code, doc anchors, recent tasks and sibling-fix lessons. `delta` when
  *  identical grounding was already served this session, null when Hunch knows
  *  nothing about the file. Serves the pre-edit hook and files a shell command
- *  wrote (which never pass through the edit tools). */
-function fileGrounding(root, store, provider, evt, target, abs) {
+ *  wrote (which never pass through the edit tools). `ledgerRoot` is where the prompt's
+ *  task lives — the process root when the event was re-rooted to a linked worktree. */
+function fileGrounding(root, store, provider, evt, target, abs, ledgerRoot = root) {
     // Decision-grounding for PROSE (doc≠graph): a markdown target that declares
     // <!-- hunch:topic … --> anchors gets each topic's CURRENT decision — the
     // graph outranks the prose being edited, and a stale pin is called out inline.
@@ -7744,7 +7844,7 @@ function fileGrounding(root, store, provider, evt, target, abs) {
     // at warning, not relevance guesses. No selection (a host without a prompt
     // hook, a legacy session, a prompt that selected nothing) keeps the unfiltered
     // grounding.
-    const selection = loadTaskSelection(hookReportTaskId(root, provider, evt));
+    const selection = loadTaskSelection(hookReportTaskId(ledgerRoot, provider, evt));
     const assembled = store.assembleContext(target);
     const selected = selection ? new Set(selection.qualifying) : null;
     const ctx = selected ? {
@@ -7779,7 +7879,7 @@ function fileGrounding(root, store, provider, evt, target, abs) {
     const retired = store.retiredForFile(target).filter((r) => r.symbols.length || r.deps.length);
     // Recent-task history is advisory; under a task selection it is dropped
     // (`hunch task list` still has it).
-    const recentTasks = selected ? [] : taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(root, hookReportTaskId(root, provider, evt), target, { excludeTargetDeliveries: true })), target);
+    const recentTasks = selected ? [] : taskSelectionSupplements(store.selectTasksAuto(target, buildTaskRankingQuery(ledgerRoot, hookReportTaskId(ledgerRoot, provider, evt), target, { excludeTargetDeliveries: true })), target);
     const hasContent = ctx.constraints.length ||
         ctx.decisions.length ||
         ctx.bugs.length ||
@@ -7843,7 +7943,7 @@ function fileGrounding(root, store, provider, evt, target, abs) {
             delivery_profile: envelope.profile, ranking_policy: envelope.ranking_policy,
         })),
     ]);
-    const reportTaskId = hookReportTaskId(root, provider, evt);
+    const reportTaskId = hookReportTaskId(ledgerRoot, provider, evt);
     // A new authoritative prompt gets its own full delivery. An earlier
     // prompt's session-level delta cannot establish this task's receipt.
     // A subagent reports to the prompt's task but starts with FRESH context:
@@ -7870,8 +7970,8 @@ function fileGrounding(root, store, provider, evt, target, abs) {
             const snapshots = snapshotDeliveredRecords(store, envelope);
             // The first time a lesson reaches this prompt's task, tell the USER in one
             // line (systemMessage); repeats of the same revision stay silent.
-            recalled = reportPresentationEnabled(root) ? renderRecalledLine(unseenLessons(root, reportTaskId, snapshots)) : null;
-            const occurrence = recordTaskDelivery(root, reportTaskId, envelope, snapshots, undefined, target);
+            recalled = reportPresentationEnabled(ledgerRoot) ? renderRecalledLine(unseenLessons(ledgerRoot, reportTaskId, snapshots)) : null;
+            const occurrence = recordTaskDelivery(ledgerRoot, reportTaskId, envelope, snapshots, undefined, target);
             reportNotice = `\n\nHunch task ${reportTaskId} · delivery ${occurrence}. Inspect exact application references with hunch_report(task_id).`;
         }
         catch {

package/dist/cli/taskReport.d.ts

@@ -4,3 +4,9 @@ export declare function registerTaskReportCommands(program: Command, openStore:
     store: HunchStore;
     root: string;
 }): void;
+/** The root whose task ledger holds `id`: `root` itself, else a sibling worktree of
+ *  the same repository that has a .hunch/. A hook rooted at the main checkout opens
+ *  the task while the agent works in a linked worktree (or the reverse); the check
+ *  still runs, and is snapshotted, where the caller stands. `root` when no sibling
+ *  has the task, so the usual "task not found" stays the error. */
+export declare function taskLedgerRoot(root: string, id: string): string;

package/dist/cli/taskReport.js

@@ -1,9 +1,11 @@
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { findRoot } from "../core/paths.js";
+import { join } from "node:path";
+import { findRoot, isDir } from "../core/paths.js";
+import { sameFilesystemEntry, worktreePaths } from "../extractors/git.js";
 import { writeFileAtomic } from "../core/io.js";
-import { finishReportTask, forgetReportTask, listReportTasks, listTaskSummaries, pruneReportHistory, readTaskReport, readLessonHistory, renderTaskStatusLine, startReportTask, summarizeTaskReport, taskReportStats } from "../core/taskReport.js";
+import { finishReportTask, forgetReportTask, reportTaskExists, listReportTasks, listTaskSummaries, pruneReportHistory, readTaskReport, readLessonHistory, renderTaskStatusLine, startReportTask, summarizeTaskReport, taskReportStats } from "../core/taskReport.js";
 import { promptTaskId } from "../core/taskReportHook.js";
-import { DEFAULT_CHECK_TIMEOUT_MS, MAX_CHECK_TIMEOUT_MS, reportSourceSnapshot, runReportCheck, runReportConformance } from "../core/taskReportEvidence.js";
+import { DEFAULT_CHECK_TIMEOUT_MS, MAX_CHECK_TIMEOUT_MS, currentSource, runReportCheck, runReportConformance } from "../core/taskReportEvidence.js";
 import { renderTaskReport, writeTaskReportHtml } from "../core/taskReportRender.js";
 import { assertReportPath } from "../core/taskReportPaths.js";
 import { publicTaskReport } from "../core/taskReportPublic.js";
@@ -61,7 +63,7 @@ export function registerTaskReportCommands(program, openStore) {
         catch (error) {
             graph = `\nGraph     not saved: ${error.message}`;
         }
-        console.log(renderTaskReport(readTaskReport(root, id, reportSourceSnapshot(root).hash)) + graph);
+        console.log(renderTaskReport(readTaskReport(root, id, currentSource(root))) + graph);
     });
     task.command("list").description("Recent tasks observed in this repository with what Hunch delivered, saved, guarded, and checked")
         .option("--limit <n>", "how many recent tasks (max 30)", "30")
@@ -69,7 +71,7 @@ export function registerTaskReportCommands(program, openStore) {
         .action((opts) => {
         const root = findRoot();
         const limit = Number(opts.limit) || 30;
-        let summaries = listTaskSummaries(root, limit, reportSourceSnapshot(root).hash);
+        let summaries = listTaskSummaries(root, limit, currentSource(root));
         // Graph records (this machine's or a teammate's) join the local ledger view.
         try {
             const opened = openStore();
@@ -161,7 +163,7 @@ export function registerTaskReportCommands(program, openStore) {
         catch { /* a malformed host payload falls back to the most recent task */ }
         let summary = null;
         try {
-            const snapshot = reportSourceSnapshot(root).hash;
+            const snapshot = currentSource(root);
             summary = taskId ? summarizeTaskReport(root, taskId, snapshot) : listTaskSummaries(root, 1, snapshot)[0] ?? null;
         }
         catch {
@@ -207,7 +209,9 @@ export function registerTaskReportCommands(program, openStore) {
         process.on("SIGINT", interrupt);
         process.on("SIGTERM", terminate);
         try {
-            const result = await runReportCheck(findRoot(), id, command, opts.label, seconds * 1000, {
+            const here = findRoot();
+            const result = await runReportCheck(taskLedgerRoot(here, id), id, command, opts.label, seconds * 1000, {
+                workRoot: here,
                 signal: controller.signal,
                 onStdout: opts.json ? undefined : chunk => { process.stdout.write(chunk); },
                 onStderr: opts.json ? undefined : chunk => { process.stderr.write(chunk); },
@@ -258,7 +262,7 @@ export function registerTaskReportCommands(program, openStore) {
         }
         let report;
         try {
-            report = readTaskReport(root, id, reportSourceSnapshot(root).hash);
+            report = readTaskReport(root, id, currentSource(root));
         }
         catch (error) {
             // Not in this machine's ledger: the graph record (if any) is what remains.
@@ -277,6 +281,25 @@ export function registerTaskReportCommands(program, openStore) {
         console.log(opts.json ? JSON.stringify(report, null, 2) : renderTaskReport(report));
     });
 }
+/** The root whose task ledger holds `id`: `root` itself, else a sibling worktree of
+ *  the same repository that has a .hunch/. A hook rooted at the main checkout opens
+ *  the task while the agent works in a linked worktree (or the reverse); the check
+ *  still runs, and is snapshotted, where the caller stands. `root` when no sibling
+ *  has the task, so the usual "task not found" stays the error. */
+export function taskLedgerRoot(root, id) {
+    if (reportTaskExists(root, id))
+        return root;
+    for (const other of worktreePaths(root)) {
+        if (sameFilesystemEntry(other, root) || !isDir(join(other, ".hunch")) || !existsSync(join(other, ".hunch-cache", "served.db")))
+            continue;
+        try {
+            if (reportTaskExists(other, id))
+                return other;
+        }
+        catch { /* unreadable ledger: keep looking */ }
+    }
+    return root;
+}
 function readStdinText() {
     return new Promise(resolve => {
         let data = "";

package/dist/core/correction.d.ts

@@ -1,4 +1,6 @@
 import type { Constraint } from "./types.js";
+/** The prompt with host-generated blocks removed: what the human actually typed. */
+export declare function stripHostBlocks(prompt: string): string;
 export declare function looksLikeCorrection(prompt: string | undefined | null): boolean;
 /** One-line nudge appended to the UserPromptSubmit hook context when a prompt
  *  reads like a correction — surfaces the write tool so the rule gets ENFORCED,

package/dist/core/correction.js

@@ -29,10 +29,24 @@ const CORRECTION_PATTERNS = [
     /\b(undo|revert) (that|this|it|your)\b/i,
     /\b(not like that|don'?t do (that|this)( again)?|stop doing (that|this))\b/i,
 ];
+/** Host-generated blocks a prompt can carry: a background task's completion
+ *  (`<task-notification>`, which also wraps a subagent's hand-back report),
+ *  injected context (`<system-reminder>`, hook output) and the browser
+ *  extension's standing instructions (`<browser_instruction>`). Their words are not the
+ *  human's, so "never use X" quoted from a constraint is not a correction. A tag
+ *  left unclosed drops only the rest of its own line, never the human's text below. */
+const HOST_TAGS = "task-notification|system-reminder|local-command-stdout|local-command-stderr|command-message|command-name|command-args|browser_instruction";
+const HOST_BLOCK = new RegExp(`<(${HOST_TAGS})>[\\s\\S]*?<\\/\\1>`, "gi");
+const HOST_OPEN_LINE = new RegExp(`<(?:${HOST_TAGS})>[^\\n]*`, "gi");
+/** The prompt with host-generated blocks removed: what the human actually typed. */
+export function stripHostBlocks(prompt) {
+    return prompt.replace(HOST_BLOCK, " ").replace(HOST_OPEN_LINE, " ");
+}
 export function looksLikeCorrection(prompt) {
     if (!prompt || typeof prompt !== "string")
         return false;
-    return CORRECTION_PATTERNS.some((re) => re.test(prompt));
+    const human = stripHostBlocks(prompt);
+    return CORRECTION_PATTERNS.some((re) => re.test(human));
 }
 /** One-line nudge appended to the UserPromptSubmit hook context when a prompt
  *  reads like a correction — surfaces the write tool so the rule gets ENFORCED,

package/dist/core/subagentrole.d.ts

@@ -0,0 +1,6 @@
+/** Whether a delegated agent can call Hunch's MCP tools. A named role defined in
+ *  `.claude/agents/<type>.md` (project first, then user) with a `tools:` list that
+ *  names no `mcp__hunch` tool and no wildcard cannot: telling it to call
+ *  hunch_why only costs it a failed lookup. Built-in and unknown types inherit
+ *  the parent's tools. */
+export declare function roleHasHunchTools(root: string, agentType: string, home?: string): boolean;