@tech-leads-club/harness-toolkit 0.8.0 → 0.9.0

package/docs/log.md

@@ -13,6 +13,10 @@ Generated from `docs/decisions/` — do not edit by hand. Run `node tools/render
 A reserved file of the [OKF v0.1](/decisions/ad-013.md) bundle: entries grouped under ISO 8601 headings,
 newest first. For what landed in which npm release, see `CHANGELOG.md` at the repository root.
 
+## 2026-08-29
+
+- **AD-114** — Rule proof `since HEAD` resolves sha from the event's own working directory, not the project root ([/decisions/ad-114.md](/decisions/ad-114.md))
+
 ## 2026-08-26
 
 - **AD-106** — A build step's own exit code cannot be the publish guarantee when it is also a recovery path ([/decisions/ad-106.md](/decisions/ad-106.md))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tech-leads-club/harness-toolkit",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "type": "module",
   "description": "Multi-provider agent steering: gates, follow-up, handoff, policy",
   "keywords": [

package/src/contracts/harness-event.ts

@@ -52,6 +52,13 @@ export type HarnessEvent = {
   event: HarnessEventKind;
   sessionKey: string;
   projectDir: string;
+  /**
+   * The host's own report of the actual working directory for this event — the worktree root after
+   * the agent enters one, or the directory after a `cd` ([/decisions/ad-114.md](/decisions/ad-114.md)).
+   * Absent when the host does not report a per-event working directory. Distinct from `projectDir`,
+   * which anchors state/config and deliberately does not move into a worktree.
+   */
+  cwd?: string;
   // hazard: the `spawn*` pair describes the child of a spawn; the unprefixed fields describe the
   // running agent. Conflating them clobbers sticky parent state.
   model?: string;

package/src/entrypoints/stop.ts

@@ -13,7 +13,13 @@ import {
 import { flagsDir } from "../platform/paths.ts";
 import type { Handler, HandlerContext } from "./run.ts";
 import { main } from "./run.ts";
-import { currentGitSha, formatLessonsBlock, obsConfigFor, sessionIdFromKey } from "./support.ts";
+import {
+  currentGitSha,
+  formatLessonsBlock,
+  obsConfigFor,
+  sessionIdFromKey,
+  shaScopeRoot,
+} from "./support.ts";
 
 const STAGNATION_FOLLOWUP = [
   "BLOCKED: identical validation fingerprint repeated — no progress between attempts.",
@@ -31,6 +37,7 @@ const STAGNATION_FOLLOWUP = [
  */
 async function observeGateForRules(args: {
   root: string;
+  shaRoot: string;
   sessionKey: string;
   policy: Policy;
   gate: string;
@@ -40,7 +47,7 @@ async function observeGateForRules(args: {
     return;
   }
   coreFacade.rules.observeGate(args.root, args.policy.rules, args.gate, {
-    sha: await currentGitSha(args.root),
+    sha: await currentGitSha(args.shaRoot),
     sessionKey: args.sessionKey,
     at: new Date().toISOString(),
   });
@@ -179,6 +186,7 @@ async function creditPendingLessons(args: {
 
 async function runLockedGate(args: {
   root: string;
+  shaRoot: string;
   provider: string;
   session: string;
   gate: "lint" | "test" | "docs";
@@ -429,6 +437,7 @@ async function failGate(args: {
  */
 async function decideStopRules(
   root: string,
+  shaRoot: string,
   policy: Policy,
   sessionKey: string,
 ): Promise<ReturnType<typeof coreFacade.rules.decideStop>> {
@@ -439,13 +448,14 @@ async function decideStopRules(
   }
   return coreFacade.rules.decideStop(root, policy.rules, {
     ...context,
-    sha: await currentGitSha(root),
+    sha: await currentGitSha(shaRoot),
   });
 }
 
 export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerContext): Promise<Decision> => {
   const { policy, capabilities } = ctx;
   const root = event.projectDir;
+  const shaRoot = shaScopeRoot(event);
   const provider = event.provider;
   const sessionKey = event.sessionKey;
   const session = sessionIdFromKey(event);
@@ -562,6 +572,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
   if (policy.grind.enabled && policy.grind.lintCommand && codeTargets.length > 0) {
     const run = await runLockedGate({
       root,
+      shaRoot,
       provider,
       session,
       pendingCredit,
@@ -599,6 +610,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
       const recordFiles = testTargets.length > 0 ? testTargets : codeTargets;
       const run = await runLockedGate({
         root,
+        shaRoot,
         provider,
         session,
         pendingCredit,
@@ -757,6 +769,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
   if (policy.docs.command && policy.docs.command.length > 0) {
     const run = await runLockedGate({
       root,
+      shaRoot,
       provider,
       session,
       pendingCredit,
@@ -900,7 +913,7 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
    * invariant: `warn` returns `context`, which does not block. Everything else refuses the stop, so a rule the
    * operator wrote cannot be ended past.
    */
-  const stopRules = await decideStopRules(root, policy, sessionKey);
+  const stopRules = await decideStopRules(root, shaRoot, policy, sessionKey);
   if (stopRules.decision.kind !== "abstain") {
     if (stopRules.decision.kind !== "context") {
       const worst = coreFacade.rules.strictest(stopRules.outcomes);

package/src/entrypoints/support.ts

@@ -58,6 +58,18 @@ export async function currentGitBranch(root: string): Promise<string | null> {
   return branch.length > 0 ? branch : null;
 }
 
+/**
+ * why: `event.projectDir` prefers `CLAUDE_PROJECT_DIR`, which the host deliberately keeps pointed at the
+ * session's original root — including inside a git worktree, where it would otherwise return the wrong
+ * HEAD for a `since HEAD` rule proof. `event.cwd` is the field the host actually moves when the agent is
+ * working in a worktree or after a `cd`. Only the rules engine's proof sha needs this; every other use of
+ * `event.projectDir` (state dir, policy config, presence) is deliberately left alone
+ * ([/decisions/ad-114.md](/decisions/ad-114.md)).
+ */
+export function shaScopeRoot(event: HarnessEvent): string {
+  return event.cwd ?? event.projectDir;
+}
+
 export async function currentGitSha(root: string): Promise<string | null> {
   if (!existsSync(join(root, ".git"))) {
     return null;
@@ -205,7 +217,7 @@ export async function observeForRules(
   if (!coreFacade.rules.wants(event.projectDir, config, event)) {
     return;
   }
-  const sha = await currentGitSha(event.projectDir);
+  const sha = await currentGitSha(shaScopeRoot(event));
   coreFacade.rules.observe(event.projectDir, config, event, {
     sha,
     sessionKey: event.sessionKey,

package/src/entrypoints/tool-before.ts

@@ -2,7 +2,13 @@ import type { Decision, HarnessEvent } from "../contracts/index.ts";
 import { coreFacade } from "../core/index.ts";
 import type { Handler, HandlerContext } from "./run.ts";
 import { main } from "./run.ts";
-import { currentGitSha, obsConfigFor, readModelFromToolInput, subagentSpawnInput } from "./support.ts";
+import {
+  currentGitSha,
+  obsConfigFor,
+  readModelFromToolInput,
+  shaScopeRoot,
+  subagentSpawnInput,
+} from "./support.ts";
 
 const READONLY_BLOCKED_TOOLS = new Set(["Write", "Delete", "Shell"]);
 
@@ -61,7 +67,7 @@ async function rulesDecision(event: HarnessEvent, ctx: HandlerContext): Promise<
   }
   // why twice: the first pass answers whether any rule fired at all, which costs no git. Only then is the sha
   // worth a process, and the second pass is the one whose verdict counts.
-  const sha = await currentGitSha(event.projectDir);
+  const sha = await currentGitSha(shaScopeRoot(event));
   const verdict = coreFacade.rules.decideAction(event.projectDir, config, trigger, {
     sha,
     sessionKey: event.sessionKey,

package/src/providers/claude/claude.inbound.ts

@@ -119,6 +119,14 @@ export function claudeToEvent(raw: Record<string, unknown>): HarnessEvent | null
     event.permissionMode = permissionMode;
   }
 
+  // why: `cwd` is a common field on every Claude hook payload, and the host docs confirm it tracks the
+  // agent into a worktree or after a `cd` — unlike `projectDir`, which stays at the session's original
+  // root ([/decisions/ad-114.md](/decisions/ad-114.md)).
+  const cwd = asString(raw.cwd);
+  if (cwd) {
+    event.cwd = cwd;
+  }
+
   const isSpawnEvent = eventKind === "subagent.start" || eventKind === "subagent.stop";
   const model = isSpawnEvent ? undefined : asString(raw.model);
   if (model) {

package/src/providers/cursor/cursor.inbound.ts

@@ -142,6 +142,16 @@ export function cursorToEvent(raw: Record<string, unknown>): HarnessEvent | null
       if (output !== undefined) {
         event.toolOutput = output;
       }
+      // why: confirmed against cursor.com/docs/hooks — `cwd` exists only on `beforeShellExecution`
+      // (this event's `shell.before` half), not on `afterShellExecution` or any other event this
+      // adapter maps. Never guessed onto an event kind the host does not report it for
+      // ([/decisions/ad-114.md](/decisions/ad-114.md)).
+      if (eventKind === "shell.before") {
+        const cwd = asString(raw.cwd);
+        if (cwd !== undefined) {
+          event.cwd = cwd;
+        }
+      }
       break;
     }
     case "mcp.before":