@tech-leads-club/harness-toolkit 0.3.6 → 0.4.0

package/src/core/rules/rules.service.ts

@@ -0,0 +1,141 @@
+/**
+ * The composition the entrypoints call: read the rules, see what fired, decide.
+ *
+ * why here and not in the entrypoint: the entrypoints are adapters. Which rules apply, what proves them and what
+ * the verdict is are all decisions, and decisions live in core ([/decisions/ad-016.md](/decisions/ad-016.md)).
+ *
+ * invariant: with the capability off, or with no rule files, this reads two directory entries and returns nothing.
+ * That is what makes the feature inert until an operator declares something (AC1).
+ */
+import type { Decision } from "../../contracts/decision.ts";
+import type { OperatorMode } from "../policy/policy.types.ts";
+import { actionDecision, evaluateRules, type RuleOutcome, stopDecision, strictest } from "./rules.decide.ts";
+import {
+  gateObservation,
+  type ObservableEvent,
+  type ObserveContext,
+  observationFrom,
+  observedFact,
+} from "./rules.observe.ts";
+import { buildRuleSet } from "./rules.parse.ts";
+import { kindIsRequired } from "./rules.proof.ts";
+import { readObservations, readRuleSources, recordObservation } from "./rules.store.ts";
+import { firingRules, type TriggerContext } from "./rules.trigger.ts";
+import type { RuleError, RuleSet } from "./rules.types.ts";
+
+export type RulesConfig = { enabled: boolean };
+
+export function loadRules(root: string, config: RulesConfig): RuleSet {
+  if (!config.enabled) {
+    return { rules: [], disabled: [], errors: [] };
+  }
+  return buildRuleSet(readRuleSources(root));
+}
+
+/**
+ * Whether this event is worth a sha.
+ *
+ * hazard: nothing called `observe` at all in the first cut of this feature. The store was never written, so no
+ * proof could exist, so every rule that parsed denied for ever — and `require:` is mandatory, so that was every
+ * rule. The end-to-end run that appeared to show the loop working was a script calling `observe` by hand, which
+ * supplied the missing half and hid it ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * why the question is asked before the answer is fetched: the observing rails fire on every tool call and the sha
+ * is a process spawn. An operator whose only rule wants `subagent(the-jury)` pays two directory reads per command
+ * and no git at all.
+ */
+export function wantsObservation(root: string, config: RulesConfig, event: ObservableEvent): boolean {
+  const fact = observedFact(event);
+  return fact !== null && kindIsRequired(loadRules(root, config).rules, fact.kind);
+}
+
+/** invariant: with the capability off nothing is written, so a machine that never opted in carries no new file. */
+export function observe(
+  root: string,
+  config: RulesConfig,
+  event: ObservableEvent,
+  context: ObserveContext,
+): void {
+  if (!config.enabled) {
+    return;
+  }
+  const observation = observationFrom(event, context);
+  if (observation !== null) {
+    recordObservation(root, observation);
+  }
+}
+
+/**
+ * A gate is the one proof the harness decides rather than witnesses, so it is recorded where it is decided.
+ *
+ * invariant: only a gate that passed. Recording a failure as an observation would make "the gate ran" satisfy a
+ * rule that asked for "the gate passed".
+ */
+export function wantsGateObservation(root: string, config: RulesConfig): boolean {
+  return kindIsRequired(loadRules(root, config).rules, "gate");
+}
+
+export function observeGate(root: string, config: RulesConfig, gate: string, context: ObserveContext): void {
+  if (!config.enabled) {
+    return;
+  }
+  recordObservation(root, gateObservation(gate, context));
+}
+
+export type RulesVerdict = {
+  decision: Decision;
+  /** Everything that fired, so a `follow-up` or a `warn` can be reported even when the action is allowed. */
+  outcomes: RuleOutcome[];
+  errors: RuleError[];
+};
+
+const NOTHING: RulesVerdict = { decision: { kind: "abstain" }, outcomes: [], errors: [] };
+
+/**
+ * The action-time answer. `deny` and `ask` block here; `follow-up` and `warn` are answers to the end of a turn and
+ * to the record, so they abstain and are returned for the caller to report.
+ */
+export function decideAction(
+  root: string,
+  config: RulesConfig,
+  trigger: TriggerContext,
+  context: RuleContext,
+): RulesVerdict {
+  return decide(root, config, trigger, context, actionDecision);
+}
+
+/**
+ * The end-of-turn answer, and the only caller that can see an `on: stop` rule.
+ *
+ * why a second entry rather than a flag: the trigger is fixed and the mapping differs, so a boolean would make one
+ * function answer two questions ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+export function decideStop(root: string, config: RulesConfig, context: RuleContext): RulesVerdict {
+  return decide(root, config, { event: "stop" }, context, stopDecision);
+}
+
+export type RuleContext = { sha: string | null; sessionKey: string; mode: OperatorMode };
+
+function decide(
+  root: string,
+  config: RulesConfig,
+  trigger: TriggerContext,
+  context: RuleContext,
+  map: (outcome: RuleOutcome) => Decision,
+): RulesVerdict {
+  const set = loadRules(root, config);
+  if (set.rules.length === 0 && set.errors.length === 0) {
+    return NOTHING;
+  }
+  const firing = firingRules(set.rules, trigger);
+  if (firing.length === 0) {
+    return { ...NOTHING, errors: set.errors };
+  }
+  const outcomes = evaluateRules(firing, readObservations(root), context);
+  const worst = strictest(outcomes);
+  return {
+    decision: worst === null ? { kind: "abstain" } : map(worst),
+    outcomes,
+    errors: set.errors,
+  };
+}

package/src/core/rules/rules.store.ts

@@ -0,0 +1,77 @@
+/**
+ * Where the harness records what it observed, and where it reads the rules from.
+ *
+ * invariant: the agent cannot write here. This lives under the project state directory, which the floor's
+ * `policy-surface-write` refuses to an agent through a shell redirect, an interpreter or a write tool — and the
+ * mutating `tlc harness` subcommands are refused from inside a session. So the only writer is the harness
+ * observing a host event, which is what makes a proof unforgeable rather than conventional
+ * ([/decisions/ad-100.md](/decisions/ad-100.md), [/decisions/ad-022.md](/decisions/ad-022.md)).
+ *
+ * why append-only jsonl and not a merged document: two sessions observe at the same time, and an append is the one
+ * write that needs no lock. The reader takes the tail, because a proof is about now.
+ */
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { appendRecord, readTail } from "../../platform/fs-jsonl.ts";
+import { machineHome, projectStateDir } from "../../platform/paths.ts";
+import type { RuleSource } from "./rules.parse.ts";
+import type { Observation } from "./rules.proof.ts";
+import type { RuleTier } from "./rules.types.ts";
+
+/**
+ * why a bound: an observation older than this window cannot satisfy `since HEAD` anyway, and a file that grows
+ * without limit is a file nobody prunes. The tail is generous enough that a long session keeps its own proofs.
+ */
+const OBSERVATION_TAIL = 500;
+
+export function observationsPath(root: string): string {
+  return join(projectStateDir(root), "rule-observations.jsonl");
+}
+
+/** The project's rules, versioned with it. */
+export function projectRulesDir(root: string): string {
+  return join(projectStateDir(root), "..", "rules");
+}
+
+/** This machine's rules, every repository — the tier that follows the operator across products. */
+export function globalRulesDir(): string {
+  return join(machineHome(), "rules");
+}
+
+function readDir(dir: string, tier: RuleTier): RuleSource[] {
+  if (!existsSync(dir)) {
+    return [];
+  }
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && entry.name.endsWith(".md"))
+    .map((entry) => {
+      const path = join(dir, entry.name);
+      return { name: basename(entry.name, ".md"), tier, text: readFileSync(path, "utf8") };
+    });
+}
+
+/**
+ * invariant: both tiers are read, global first, so `buildRuleSet` can let the project win by name. Absent
+ * directories are absent rules, not an error — no rules means no behaviour change
+ * ([/decisions/ad-040.md](/decisions/ad-040.md)).
+ */
+export function readRuleSources(root: string): RuleSource[] {
+  return [...readDir(globalRulesDir(), "global"), ...readDir(projectRulesDir(root), "project")];
+}
+
+export function recordObservation(root: string, observation: Observation): void {
+  try {
+    appendRecord(observationsPath(root), observation);
+  } catch {
+    // why swallowed: an unwritable state directory must not fail the turn that was being observed. The proof will
+    // be missing, which the gate reports as missing rather than as an error nobody can act on.
+  }
+}
+
+export function readObservations(root: string): Observation[] {
+  try {
+    return readTail<Observation>(observationsPath(root), OBSERVATION_TAIL);
+  } catch {
+    return [];
+  }
+}

package/src/core/rules/rules.trigger.ts

@@ -0,0 +1,101 @@
+/**
+ * Whether a rule's trigger fires on this event.
+ *
+ * invariant: pure, and it never reads a host payload. It takes the published event shape, so a rule written once
+ * fires the same way on every provider ([/decisions/ad-004.md](/decisions/ad-004.md)).
+ *
+ * hazard: a shell trigger cannot be a substring test against the whole command. `x && gh pr create` is a pull
+ * request being opened, and a heredoc body containing the words `gh pr create` is a document. `tokenizeShell`
+ * separates both and is the only splitter in this repository — a second regex here would be the duplication that
+ * makes one of them wrong later ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+import { tokenizeShell } from "../floor/floor.tokenize.ts";
+import type { Rule, RuleTrigger } from "./rules.types.ts";
+
+/**
+ * What the harness reads to decide whether a trigger fires. A subset of the event, named so the vocabulary is
+ * visible: adding a trigger that needs a new field has to widen this deliberately.
+ */
+export type TriggerContext = {
+  event: string;
+  toolName?: string;
+  command?: string;
+};
+
+/**
+ * why a set per trigger rather than one pattern the operator writes: `pr-open` has to mean the same thing in
+ * every repository, or a rule copied between them silently stops firing. An operator who wants their own shape
+ * writes `command(<pattern>)`.
+ */
+const SHELL_SHAPES: Record<"pr-open" | "commit" | "push", readonly string[][]> = {
+  "pr-open": [
+    ["gh", "pr", "create"],
+    ["gh", "pr", "ready"],
+  ],
+  commit: [["git", "commit"]],
+  push: [["git", "push"]],
+};
+
+/**
+ * invariant: `tokenizeShell` already declines to emit segments from a heredoc body, so a body is never mistaken
+ * for a command and a command after one is still seen. Measured both ways on
+ * `cat <<EOF > runbook.md\ngh pr create --fill\nEOF` and on the same with a real command after the terminator:
+ * identical output.
+ *
+ * hazard: the first version of this called `splitHeredocs` first as well. It changed nothing — the mutation that
+ * removed it survived, which is what exposed it as dead rather than as untested
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+function subCommands(command: string): string[][] {
+  return tokenizeShell(command)
+    .map((segment) => segment.words.map((word) => word.text))
+    .filter((words) => words.length > 0);
+}
+
+/** why prefix rather than equality: `gh pr create --fill --base main` is the same act as `gh pr create`. */
+function startsWithShape(words: readonly string[], shape: readonly string[]): boolean {
+  return shape.every((token, index) => words[index] === token);
+}
+
+/**
+ * why a phrase and not a word: an operator writes `command(gh pr review)`, meaning those words in that order.
+ * Matching the raw string against the whole command would let a heredoc or an unrelated argument satisfy it.
+ */
+export function matchesPhrase(words: readonly string[], pattern: string): boolean {
+  const phrase = pattern.trim().split(/\s+/);
+  if (phrase.length === 0) {
+    return false;
+  }
+  return words.some((_, start) => phrase.every((token, index) => words[start + index] === token));
+}
+
+export function triggerMatches(trigger: RuleTrigger, context: TriggerContext): boolean {
+  switch (trigger.kind) {
+    case "stop":
+      return context.event === "stop";
+    case "tool":
+      return context.toolName === trigger.name;
+    case "pr-open":
+    case "commit":
+    case "push": {
+      if (context.command === undefined) {
+        return false;
+      }
+      const shapes = SHELL_SHAPES[trigger.kind];
+      return subCommands(context.command).some((words) =>
+        shapes.some((shape) => startsWithShape(words, shape)),
+      );
+    }
+    default: {
+      if (context.command === undefined) {
+        return false;
+      }
+      return subCommands(context.command).some((words) => matchesPhrase(words, trigger.pattern));
+    }
+  }
+}
+
+/** invariant: a disabled rule never fires. It exists to switch a global off and to record why. */
+export function firingRules(rules: readonly Rule[], context: TriggerContext): Rule[] {
+  return rules.filter((rule) => rule.enabled && triggerMatches(rule.on, context));
+}

package/src/core/rules/rules.types.ts

@@ -0,0 +1,64 @@
+/**
+ * What an operator rule is.
+ *
+ * why two closed vocabularies: a gate may only rest on something the harness observed, and a trigger may only be
+ * something it can recognise. An open expression language would let an operator declare a rule the harness cannot
+ * evaluate, and the honest answer to that is a parse error rather than a rule that never fires
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+
+/** Where the rule came from. `project` replaces a `global` of the same name, and both apply otherwise. */
+export type RuleTier = "global" | "project";
+
+/**
+ * What happens when the proof is missing.
+ *
+ * invariant: `deny`, `follow-up` and `warn` are verification and are identical at every posture. `ask` is an
+ * interruption, which is the one thing posture governs ([/decisions/ad-025.md](/decisions/ad-025.md)).
+ */
+export type RuleVerdict = "deny" | "ask" | "follow-up" | "warn";
+
+export const RULE_VERDICTS: ReadonlySet<string> = new Set<RuleVerdict>(["deny", "ask", "follow-up", "warn"]);
+
+/** When the rule is evaluated. */
+export type RuleTrigger =
+  | { kind: "pr-open" }
+  | { kind: "commit" }
+  | { kind: "push" }
+  | { kind: "stop" }
+  | { kind: "tool"; name: string }
+  | { kind: "command"; pattern: string };
+
+/**
+ * What counts as proof, and how fresh it must be.
+ *
+ * why `head` by default: a review of the code as it was two commits ago is not a review of what the pull request
+ * carries.
+ */
+export type ProofWindow = "head" | "session";
+
+export type RuleProof =
+  | { kind: "subagent"; value: string; since: ProofWindow }
+  | { kind: "command"; value: string; since: ProofWindow }
+  | { kind: "gate"; value: string; since: ProofWindow }
+  | { kind: "file"; value: string; since: ProofWindow };
+
+export const PROOF_KINDS: ReadonlySet<string> = new Set(["subagent", "command", "gate", "file"]);
+
+export type Rule = {
+  /** The file name without its extension. This is the id the tiers dedupe on. */
+  name: string;
+  tier: RuleTier;
+  enabled: boolean;
+  on: RuleTrigger;
+  /** invariant: every proof must hold. There is no boolean algebra here on purpose. */
+  require: RuleProof[];
+  otherwise: RuleVerdict;
+  /** The operator's own text, injected verbatim when the rule fires. */
+  body: string;
+};
+
+/** A rule that could not be read. Named, so `doctor` can report it instead of the harness ignoring it silently. */
+export type RuleError = { name: string; tier: RuleTier; error: string };
+
+export type RuleSet = { rules: Rule[]; errors: RuleError[]; disabled: Rule[] };

package/src/entrypoints/shim.ts

@@ -79,6 +79,14 @@ if (existsSync(execBin)) {
 } else if (existsSync(srcHandler)) {
   run(process.env.BUN_BIN || "bun", ["run", srcHandler]);
 } else {
+  /**
+   * hazard: this exited 127 with nothing on stdout. The project shim answers a host hook, so a shim that cannot
+   * find its handler was standing between the agent and its tools with no verdict at all — the same defect the
+   * launcher had one layer down ([/decisions/ad-101.md](/decisions/ad-101.md)).
+   *
+   * invariant: the diagnosis still reaches stderr. Failing open is not failing silently.
+   */
   console.error(`tlc shim: handler not found: ${handler}`);
-  process.exit(127);
+  process.stdout.write("{}");
+  process.exit(0);
 }

package/src/entrypoints/stop.ts

@@ -13,7 +13,7 @@ import {
 import { flagsDir } from "../platform/paths.ts";
 import type { Handler, HandlerContext } from "./run.ts";
 import { main } from "./run.ts";
-import { formatLessonsBlock, obsConfigFor, sessionIdFromKey } from "./support.ts";
+import { currentGitSha, formatLessonsBlock, obsConfigFor, sessionIdFromKey } from "./support.ts";
 
 const STAGNATION_FOLLOWUP = [
   "BLOCKED: identical validation fingerprint repeated — no progress between attempts.",
@@ -21,6 +21,31 @@ const STAGNATION_FOLLOWUP = [
   "NEED: change approach. Do not repeat the same fix. Inspect root cause, try a different path, or escalate with BLOCKED/TRIED/NEED.",
 ].join("\n");
 
+/**
+ * A gate is the one proof the harness decides rather than witnesses, so it is recorded where every gate already
+ * funnels through — the same argument `recordGateOutcome` makes for itself: a gate added later cannot be
+ * forgotten ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * invariant: only a gate that passed. Recording a failure would let "the gate ran" satisfy a rule that asked for
+ * "the gate passed", which is the whole point of asking.
+ */
+async function observeGateForRules(args: {
+  root: string;
+  sessionKey: string;
+  policy: Policy;
+  gate: string;
+  passed: boolean;
+}): Promise<void> {
+  if (!args.passed || !coreFacade.rules.wantsGate(args.root, args.policy.rules)) {
+    return;
+  }
+  coreFacade.rules.observeGate(args.root, args.policy.rules, args.gate, {
+    sha: await currentGitSha(args.root),
+    sessionKey: args.sessionKey,
+    at: new Date().toISOString(),
+  });
+}
+
 /**
  * hazard: `gate.outcome` was consumed in two places — the rollup counter and the session report's
  * "Gates pass/fail" line — and emitted by nothing. Both read structurally zero, so the report printed a
@@ -200,6 +225,7 @@ async function runLockedGate(args: {
 
   // invariant: recorded outside the lock. A measurement must not widen the window in which one gate blocks another.
   recordGateOutcome({ ...args, artifact, reused: cached !== null });
+  await observeGateForRules({ ...args, gate: args.gate, passed: artifact.passed });
   await creditPendingLessons({
     root: args.root,
     provider: args.provider,
@@ -387,6 +413,28 @@ async function failGate(args: {
   return { kind: "continue", text: parts.join("\n") };
 }
 
+/**
+ * why the sha is fetched twice-or-never: `git rev-parse` is a process spawn and this runs on every stop. The first
+ * pass answers whether any `on: stop` rule fired at all, which costs two directory reads; only then is a sha worth
+ * a process, and the second pass is the one whose verdict counts. Same shape as the action-time rail
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+async function decideStopRules(
+  root: string,
+  policy: Policy,
+  sessionKey: string,
+): Promise<ReturnType<typeof coreFacade.rules.decideStop>> {
+  const context = { sessionKey, mode: policy.mode };
+  const dryRun = coreFacade.rules.decideStop(root, policy.rules, { ...context, sha: null });
+  if (dryRun.outcomes.length === 0) {
+    return dryRun;
+  }
+  return coreFacade.rules.decideStop(root, policy.rules, {
+    ...context,
+    sha: await currentGitSha(root),
+  });
+}
+
 export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerContext): Promise<Decision> => {
   const { policy, capabilities } = ctx;
   const root = event.projectDir;
@@ -829,6 +877,32 @@ export const stopHandler: Handler = async (event: HarnessEvent, ctx: HandlerCont
     });
   }
 
+  /**
+   * The operator's own bar, last among the blockers so every gate the harness owns has already spoken — and after
+   * the gates specifically, because a rule asking for `gate(lint) since HEAD` can only be satisfied once lint has
+   * run this turn ([/decisions/ad-100.md](/decisions/ad-100.md)).
+   *
+   * 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);
+  if (stopRules.decision.kind !== "abstain") {
+    if (stopRules.decision.kind !== "context") {
+      const worst = coreFacade.rules.strictest(stopRules.outcomes);
+      await coreFacade.handoff.patchHandoff(root, provider, {
+        slice: {
+          last_gate_result: "fail",
+          last_failure_category: "policy",
+          blockers: `Rule ${worst?.rule.name ?? "unknown"} is not satisfied for this HEAD.`,
+          next_action: worst?.missing.length
+            ? `Produce ${worst.missing.join(", ")}, then stop again.`
+            : "Satisfy the rule named in the follow-up, then stop again.",
+        },
+      });
+    }
+    return stopRules.decision;
+  }
+
   // why: the pairing of a failure with what resolved it is captured here, immediately before the record that
   // holds the failure identity is cleared. This is the one moment both halves exist
   // ([/decisions/ad-028.md](/decisions/ad-028.md)).

package/src/entrypoints/subagent-stop.ts

@@ -2,10 +2,18 @@ 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 { observeForRules } from "./support.ts";
 
 // why: no legacy predecessor covers subagent.stop verification — this reuses the same unfinished-work
 // signal (blockers/pending/in_progress/previous_gaps) already carried on the handoff slice.
-export const subagentStopHandler: Handler = (event: HarnessEvent, _ctx: HandlerContext): Decision => {
+export const subagentStopHandler: Handler = async (
+  event: HarnessEvent,
+  ctx: HandlerContext,
+): Promise<Decision> => {
+  // why before the verdict: this records that a subagent of this type finished, which is the proof an operator
+  // rule asks for. It cannot change the decision below ([/decisions/ad-100.md](/decisions/ad-100.md)).
+  await observeForRules(event, ctx);
+
   const handoff = coreFacade.handoff.readHandoff(event.projectDir, event.provider);
   const unfinishedWork =
     Boolean(handoff.blockers) ||

package/src/entrypoints/support.ts

@@ -180,3 +180,35 @@ export function formatLessonsBlock(lessons: HarnessLesson[], title: string, omit
   }
   return lines.join("\n");
 }
+
+/**
+ * The producer half of the feature: what the harness witnessed, written where only the harness can write it.
+ *
+ * hazard: this did not exist in the first cut. `observe` had no caller, so the store was never written, no proof
+ * could ever be satisfied, and every rule that parsed denied for ever — `require:` is mandatory, so that was
+ * every rule ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ *
+ * why `wants` first: this runs on every tool call and the sha is a process spawn. Nothing is asked of git unless
+ * a declared rule requires this kind of proof, so an operator whose only rule wants a subagent pays no git on any
+ * command.
+ *
+ * invariant: after the event, never able to change it. A rail that records what happened must not become a rail
+ * that decides whether it may.
+ */
+export async function observeForRules(
+  event: HarnessEvent,
+  // why the shape and not `HandlerContext`: `run.ts` already imports this module, so naming its type here would
+  // close an import cycle. Only the one field is needed.
+  ctx: { policy: { rules: Policy["rules"] } },
+): Promise<void> {
+  const config = ctx.policy.rules;
+  if (!coreFacade.rules.wants(event.projectDir, config, event)) {
+    return;
+  }
+  const sha = await currentGitSha(event.projectDir);
+  coreFacade.rules.observe(event.projectDir, config, event, {
+    sha,
+    sessionKey: event.sessionKey,
+    at: new Date().toISOString(),
+  });
+}

package/src/entrypoints/tool-after.ts

@@ -4,7 +4,7 @@ import { estimateCostUsd, mapPoolToNeutral } from "../platform/pricing.ts";
 import { readClaudeUsage } from "../providers/index.ts";
 import type { Handler, HandlerContext } from "./run.ts";
 import { main } from "./run.ts";
-import { OBS_CONFIG_AUDIT, obsConfigFor } from "./support.ts";
+import { OBS_CONFIG_AUDIT, obsConfigFor, observeForRules } from "./support.ts";
 
 const OBS_KIND_BY_EVENT: Partial<Record<HarnessEventKind, ObsKind>> = {
   "tool.after": "tool.end",
@@ -48,7 +48,12 @@ function usageGenAi(event: HarnessEvent, ctx: HandlerContext): Record<string, un
   };
 }
 
-export const toolAfterHandler: Handler = (event: HarnessEvent, ctx: HandlerContext) => {
+export const toolAfterHandler: Handler = async (event: HarnessEvent, ctx: HandlerContext) => {
+  // why here and not at `*.before`: arriving on an after-event is what says the tool ran and did not fail. A
+  // failure comes as `tool.failure`, a different event this rail never sees, and the payload carries no exit code
+  // in any of the three shapes the two hosts send ([/decisions/ad-100.md](/decisions/ad-100.md)).
+  await observeForRules(event, ctx);
+
   coreFacade.observability.recordAudit(event.projectDir, event.event, event.raw, ctx.policy.obs.globalSpool);
 
   const kind = OBS_KIND_BY_EVENT[event.event];

package/src/entrypoints/tool-before.ts

@@ -2,7 +2,7 @@ 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 { obsConfigFor, readModelFromToolInput, subagentSpawnInput } from "./support.ts";
+import { currentGitSha, obsConfigFor, readModelFromToolInput, subagentSpawnInput } from "./support.ts";
 
 const READONLY_BLOCKED_TOOLS = new Set(["Write", "Delete", "Shell"]);
 
@@ -43,6 +43,33 @@ function recordShellDecisionIfShell(event: HarnessEvent, ctx: HandlerContext, de
   }
 }
 
+/**
+ * why the sha is read here and not in `run.ts`: `git rev-parse` is a process spawn, and this fires on every tool
+ * call. It is asked for only once a rule has actually fired, so an operator who declared nothing pays nothing
+ * ([/decisions/ad-100.md](/decisions/ad-100.md)).
+ */
+async function rulesDecision(event: HarnessEvent, ctx: HandlerContext): Promise<Decision> {
+  const config = ctx.policy.rules;
+  const trigger = { event: event.event, toolName: event.toolName, command: event.command };
+  const dryRun = coreFacade.rules.decideAction(event.projectDir, config, trigger, {
+    sha: null,
+    sessionKey: event.sessionKey,
+    mode: ctx.policy.mode,
+  });
+  if (dryRun.outcomes.length === 0) {
+    return { kind: "abstain" };
+  }
+  // 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 verdict = coreFacade.rules.decideAction(event.projectDir, config, trigger, {
+    sha,
+    sessionKey: event.sessionKey,
+    mode: ctx.policy.mode,
+  });
+  return verdict.decision;
+}
+
 function handleShellBefore(event: HarnessEvent, ctx: HandlerContext): Decision {
   const { policy } = ctx;
   const decision = coreFacade.shellPolicy.evaluateShellCommand({
@@ -108,10 +135,10 @@ async function handleToolBefore(event: HarnessEvent, ctx: HandlerContext): Promi
   return { kind: "allow" };
 }
 
-export const toolBeforeHandler: Handler = (
+export const toolBeforeHandler: Handler = async (
   event: HarnessEvent,
   ctx: HandlerContext,
-): Decision | Promise<Decision> => {
+): Promise<Decision> => {
   // invariant: the floor runs first and reads no policy, so no config value and no agent edit can
   // reach a decision before it.
   const floor = coreFacade.floor.evaluateFloor({
@@ -159,6 +186,20 @@ export const toolBeforeHandler: Handler = (
     }
   }
 
+  /**
+   * The operator's own rules, after the floor and after the integrity check, because both are unconditional and a
+   * rail comes second ([/decisions/ad-077.md](/decisions/ad-077.md)).
+   *
+   * invariant: `deny` and `ask` answer here; `follow-up` and `warn` abstain and are the stop rail's business. With
+   * the capability off, or with no rule files, `decideAction` reads two directory entries and abstains — which is
+   * what keeps a machine that never opted in byte-identical to before ([/decisions/ad-100.md](/decisions/ad-100.md)).
+   */
+  const rulesVerdict = await rulesDecision(event, ctx);
+  if (rulesVerdict.kind !== "abstain") {
+    recordShellDecisionIfShell(event, ctx, rulesVerdict);
+    return rulesVerdict;
+  }
+
   switch (event.event) {
     case "shell.before":
       return handleShellBefore(event, ctx);