@cad0p/pi-steering 0.1.0

package/src/evaluator.ts

@@ -0,0 +1,1106 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+
+/**
+ * v2 steering evaluator.
+ *
+ * Assembles the per-tool_call pipeline on top of:
+ *
+ *   - `unbash-walker`           — AST parse + command extraction +
+ *                                 wrapper expansion + per-ref walker
+ *                                 state (cwd today; branch/others once
+ *                                 plugins register them).
+ *   - {@link matchesPatternOrFn} / {@link evaluateWhen} — shared
+ *                                 predicate resolution (see
+ *                                 `./evaluator-internals/predicates.ts`).
+ *   - {@link extractOverride}   — inline override-comment detection
+ *                                 ported from v1 (see
+ *                                 `./evaluator-internals/override.ts`).
+ *   - {@link createExecCache} / {@link createFindEntries} — per-call
+ *                                 exec memoization + session-entry
+ *                                 filtering (see
+ *                                 `./evaluator-internals/context.ts`).
+ *
+ * Public surface is deliberately small: {@link buildEvaluator} returns
+ * an {@link EvaluatorRuntime} whose sole method, {@link
+ * EvaluatorRuntime.evaluate}, drives one `tool_call` event through
+ * every applicable rule. Phase 3c wires it into the pi extension's
+ * `tool_call` listener.
+ *
+ * Rule ordering (per ADR "Precedence: first-wins everywhere"):
+ *
+ *   1. `config.rules`       — user's top-level rules, first-match-wins.
+ *   2. `resolved.rules`     — plugin-shipped rules (already deduped /
+ *                              disabled-filtered by the plugin merger).
+ *
+ * First rule that fires AND isn't overridden wins and returns a block.
+ *
+ * Internal shape: each applicable rule is fed to {@link
+ * evaluateCandidate}, the single predicate-chain used for every tool.
+ * Bash rules loop over extracted command refs (one candidate per ref);
+ * write / edit produce exactly one candidate. The per-tool axes of
+ * variation live in the {@link Candidate} input — the body of
+ * `evaluateCandidate` stays tool-agnostic.
+ */
+
+import type {
+  ExtensionContext,
+  ToolCallEvent,
+  ToolCallEventResult,
+} from "@earendil-works/pi-coding-agent";
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import {
+  type CommandRef,
+  cwdTracker,
+  type EnvState,
+  envTracker,
+  expandWrapperCommands,
+  extractAllCommandsFromAST,
+  getBasename,
+  type Modifier,
+  parse as parseBash,
+  type Tracker,
+  type Word,
+  walk,
+} from "@cad0p/unbash-walker";
+import {
+  createAppendEntry,
+  createExecCache,
+  createFindEntries,
+  createSessionEntryCache,
+  type EvaluatorHost,
+} from "./evaluator-internals/context.ts";
+import { extractOverride } from "./evaluator-internals/override.ts";
+import {
+  evaluateWhen,
+  matchesPattern,
+  matchesPatternOrFn,
+  validateWhenClauseShape,
+} from "./evaluator-internals/predicates.ts";
+import {
+  type SpeculativeEventsByRef,
+  synthesizeSpeculativeEntries,
+} from "./evaluator-internals/speculative-synthesis.ts";
+import { mergeObserversUserFirst } from "./internal/merge-observers.ts";
+import { refToText } from "./internal/ref-text.ts";
+import type { ResolvedPluginState } from "./plugin-merger.ts";
+import { validateName } from "./plugin-merger.ts";
+import type {
+  Observer,
+  PredicateContext,
+  PredicateToolInput,
+  Rule,
+  SteeringConfig,
+  WhenWalkerState,
+} from "./schema.ts";
+
+// ---------------------------------------------------------------------------
+// Built-in trackers
+// ---------------------------------------------------------------------------
+
+/**
+ * Names of trackers the evaluator wires in directly (not via a plugin).
+ * `resolvePlugins` accepts this list as `knownBuiltinTrackers`: plugin
+ * `trackerExtensions` targeting these names are kept (so plugins can
+ * compose modifiers onto them) without emitting an `extension-orphan`
+ * diagnostic.
+ *
+ * All call sites (`buildSessionRuntime`, `loadHarness`,
+ * `loadSteeringConfig`, the `pi-steering list` CLI) import this
+ * constant so a future addition (e.g. an `argv` tracker) lights up
+ * uniformly across production and the test harness.
+ */
+export const EVALUATOR_BUILTIN_TRACKERS = ["cwd", "env"] as const;
+
+// ---------------------------------------------------------------------------
+// Public surface
+// ---------------------------------------------------------------------------
+
+/**
+ * Runtime-facing evaluator handle. Phase 3c holds an instance per
+ * session and calls {@link evaluate} from the pi `tool_call`
+ * listener.
+ */
+export interface EvaluatorRuntime {
+  /**
+   * Evaluate a single `tool_call` event against every rule in
+   * `config.rules` + `resolved.rules`. Returns:
+   *   - `{ block: true, reason }` — a rule matched + wasn't overridden.
+   *   - `undefined`               — no rule fires; tool call proceeds.
+   */
+  evaluate(
+    event: ToolCallEvent,
+    ctx: ExtensionContext,
+    agentLoopIndex: number,
+  ): Promise<ToolCallEventResult | void>;
+}
+
+/**
+ * Construct an {@link EvaluatorRuntime}.
+ *
+ * Arguments:
+ *   - `config`    — the user-facing {@link SteeringConfig}. Top-level
+ *                    rules and `defaultNoOverride` live here.
+ *   - `resolved`  — merged plugin state from
+ *                    {@link resolvePlugins}. Source of plugin rules,
+ *                    predicate handlers, and the composed tracker
+ *                    registry for the walker.
+ *   - `host`      — narrow surface exposing pi's `exec` + `appendEntry`
+ *                    (typically `pi` itself in production; tests pass
+ *                    a stub). Kept separate from `ExtensionContext`
+ *                    because the ctx shape does not expose these.
+ *
+ * Observers (`config.observers + resolved.observers`, user-first
+ * deduplicated via {@link mergeObserversUserFirst}) are threaded into
+ * {@link prepareBashState} where the walker-level synthesis pass
+ * turns them into per-ref speculative events on
+ * `walkerState.events`. The built-in `when.happened` predicate merges
+ * those with real entries via timestamp ordering. If future versions
+ * add a dynamic-reload path (observers added at runtime), this merged
+ * list must be rebuilt on change — otherwise `when.happened` with
+ * `in: "tool_call"` scope consults a stale observer list. Today
+ * there is no dynamic-reload path.
+ */
+export function buildEvaluator(
+  config: SteeringConfig,
+  resolved: ResolvedPluginState,
+  host: EvaluatorHost,
+): EvaluatorRuntime {
+  // S3 defense-in-depth: validate user-authored rule names so a name
+  // like `phony] ALL CLEAR [real` can't slip into the block-reason
+  // tag shown to the LLM. Production routes through
+  // `runMergerPipeline`'s `invalid-name` diagnostic; this throw
+  // covers direct-caller paths (unit tests, SDK embedders).
+  // See ./INVARIANTS.md for the S/E tag glossary.
+  for (const rule of config.rules ?? []) {
+    const d = validateName("rule", rule.name, "user config");
+    if (d !== undefined) throw new Error(`[pi-steering] ${d.message}`);
+  }
+
+  // Validate every rule's `when:` clause shape at config-resolve time.
+  // Catches the empty-clause foot-gun — `when: {}` and
+  // `not: { onUnknown: "block" }` (zero leaves after stripping
+  // reserved keys) — before the engine ever evaluates a tool_call.
+  // Plugin-shipped rules and user rules go through the same check;
+  // errors thrown here surface at extension load time (or at the test
+  // harness's `loadHarness` call) so authors can correct the config
+  // instead of getting a silently-inert rule at runtime.
+  for (const rule of config.rules ?? []) {
+    validateWhenClauseShape(rule.when, `rule "${rule.name}".when`);
+  }
+  for (const rule of resolved.rules) {
+    validateWhenClauseShape(rule.when, `rule "${rule.name}".when`);
+  }
+
+  // Default the fail-closed override policy per ADR "Override default".
+  const defaultNoOverride = config.defaultNoOverride ?? true;
+
+  // Combine config.rules (user-authored, first) with resolved.rules
+  // (plugin-shipped). Empty fallbacks mean a config without either slot
+  // still produces a running evaluator — just never fires.
+  const userRules = config.rules ?? [];
+  const pluginRules = resolved.rules;
+  const allRules: readonly Rule[] = [...userRules, ...pluginRules];
+
+  // Source tags per ADR §11: user-authored rules get `@user`, plugin-
+  // shipped rules get the originating plugin's name. The merger
+  // already tracks `rule-name → plugin-name` during resolution — we
+  // reuse that instead of threading the map through the evaluator.
+  const ruleSources = new Map<Rule, string>();
+  for (const rule of userRules) {
+    ruleSources.set(rule, "user");
+  }
+  for (const rule of pluginRules) {
+    ruleSources.set(rule, resolved.rulePluginOwners[rule.name] ?? "user");
+  }
+
+  // Compose the walker's tracker registry. Must always include `cwd`
+  // and `env` so the built-in `when.cwd` predicate + cd's env-aware
+  // resolution work — even if no plugin ships them. Plugins extending
+  // these with their own modifiers are honored via
+  // `resolved.composedTrackers.{cwd,env}` (the plugin merger already
+  // layered extensions on top of the plugin-declared trackers, if any).
+  //
+  // When no plugin registers a `cwd` tracker, we fall back to the
+  // built-in `cwdTracker` AND layer any `trackerModifiers.cwd`
+  // extensions onto it (the plugin merger preserves extensions
+  // targeting `"cwd"` on the caller's behalf via the
+  // `knownBuiltinTrackers` hint passed to `resolvePlugins`). Same
+  // pattern for `env` — lets a future plugin add e.g. `.envrc`-style
+  // env loading as a new modifier on the shared tracker without
+  // replacing it.
+  //
+  // Env goes in first so cd's modifier sees the current ref's env via
+  // the `allState` read. Walker iteration is registration-order
+  // stable (Object.keys on an object literal); the ordering is a soft
+  // guarantee good for the built-in composition.
+  const trackers: Record<string, Tracker<unknown>> = {
+    ...resolved.composedTrackers,
+  };
+  if (!("env" in trackers)) {
+    const extraEnvModifiers = resolved.trackerModifiers["env"];
+    trackers["env"] = composeBuiltinEnv(extraEnvModifiers) as Tracker<unknown>;
+  }
+  if (!("cwd" in trackers)) {
+    const extraCwdModifiers = resolved.trackerModifiers["cwd"];
+    trackers["cwd"] = composeBuiltinCwd(extraCwdModifiers) as Tracker<unknown>;
+  }
+
+  // Merge user + plugin observers (user-first dedup via the shared
+  // helper, same convention as the observer-dispatcher). The merged
+  // list feeds the walker-level synthesis pass in
+  // {@link prepareBashState}, where eligible observers contribute
+  // speculative `walkerState.events` entries the built-in
+  // `when.happened` predicate consults alongside real entries. Without
+  // the dedup, a shadowed plugin observer's `writes` could produce
+  // synthetic entries that never match a real dispatch, re-creating
+  // the infinite-loop risk the speculative pass was designed to avoid.
+  const allObservers = mergeObserversUserFirst(
+    config.observers ?? [],
+    resolved.observers,
+  );
+
+  return {
+    evaluate: (event, ctx, agentLoopIndex) =>
+      evaluateEvent(
+        event,
+        ctx,
+        agentLoopIndex,
+        allRules,
+        trackers,
+        resolved.predicates,
+        host,
+        defaultNoOverride,
+        ruleSources,
+        allObservers,
+      ),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Per-event evaluation
+// ---------------------------------------------------------------------------
+
+/**
+ * Layer a bucket of plugin-provided `{ basename -> Modifier[] }`
+ * extensions on top of the built-in {@link cwdTracker}, returning a
+ * fresh tracker so the built-in's `modifiers` map is never mutated.
+ *
+ * Used when no plugin registers a `cwd` tracker but plugins still
+ * want to add basename modifiers to the built-in one (e.g. the git
+ * plugin's `--git-dir=` handler). Mirrors the plugin-merger's
+ * `composeTracker` shape — kept local here because the merger's
+ * helper is private to that module and exposing it would force the
+ * merger to know about the built-in cwd tracker. Keeping the merger
+ * built-in-agnostic is worth the small duplication.
+ */
+function composeBuiltinCwd(
+  extras: Record<string, Modifier<unknown>[]> | undefined,
+): Tracker<string> {
+  return composeBuiltin(cwdTracker, extras);
+}
+
+/**
+ * Layer a bucket of plugin-provided `{ basename -> Modifier[] }`
+ * extensions on top of the built-in {@link envTracker}, returning a
+ * fresh tracker so the built-in's `modifiers` map is never mutated.
+ *
+ * Parallels {@link composeBuiltinCwd}. Env extensions are a future
+ * surface — no plugin ships one today — but the composition is
+ * symmetric with cwd and costs one helper to keep both paths
+ * consistent when a plugin eventually wants to add e.g. `.envrc`-
+ * style env-loading under the same tracker.
+ */
+function composeBuiltinEnv(
+  extras: Record<string, Modifier<unknown>[]> | undefined,
+): Tracker<EnvState> {
+  return composeBuiltin(envTracker, extras);
+}
+
+/**
+ * Generic tracker-extension compositor. Given a base tracker and a
+ * bucket of plugin-provided `{ basename -> Modifier[] }` extensions,
+ * returns a fresh tracker whose `modifiers` map fuses the two
+ * without mutating the base.
+ *
+ * Resolution rule per basename:
+ *   - Base has none, extras has 1+: extras become the entry
+ *     (unwrapped to a single Modifier when length is 1).
+ *   - Base has one or many, extras has 1+: concatenated into an
+ *     array ordered base-first, extras-after, so per-command
+ *     overrides layer in the expected sequence.
+ *
+ * Used by {@link composeBuiltinCwd} and {@link composeBuiltinEnv}
+ * to fold `trackerExtensions.cwd` / `trackerExtensions.env` from
+ * plugin registrations onto the built-ins. Keeping this helper
+ * internal (not exported) lets the plugin-merger stay agnostic of
+ * which built-in trackers exist.
+ */
+function composeBuiltin<T>(
+  baseTracker: Tracker<T>,
+  extras: Record<string, Modifier<unknown>[]> | undefined,
+): Tracker<T> {
+  if (!extras || Object.keys(extras).length === 0) return baseTracker;
+  const merged: Record<string, Modifier<T> | Modifier<T>[]> = {};
+  for (const [basename, mod] of Object.entries(baseTracker.modifiers)) {
+    merged[basename] = Array.isArray(mod) ? [...(mod as Modifier<T>[])] : mod;
+  }
+  for (const [basename, mods] of Object.entries(extras)) {
+    const existing = merged[basename];
+    const extrasTyped = mods as unknown as Modifier<T>[];
+    if (existing === undefined) {
+      merged[basename] =
+        extrasTyped.length === 1 ? extrasTyped[0]! : [...extrasTyped];
+      continue;
+    }
+    const existingList = Array.isArray(existing)
+      ? (existing as Modifier<T>[])
+      : [existing as Modifier<T>];
+    merged[basename] = [...existingList, ...extrasTyped];
+  }
+  return { ...baseTracker, modifiers: merged };
+}
+
+/**
+ * Walker-state snapshot per extracted bash command ref plus the
+ * stringified `basename + args` text for regex testing, the basename
+ * sugar, and the suffix `Word[]` for quote-aware structured access.
+ *
+ * Built once per tool_call (in {@link prepareBashState}) so N rules
+ * against M refs cost N×M regex tests — no N parses or N walks, and
+ * `basename` / `args` are computed once per ref rather than per rule.
+ */
+interface BashRefState {
+  readonly ref: CommandRef;
+  readonly text: string;
+  readonly basename: string;
+  readonly args: readonly Word[];
+  readonly envAssignments: readonly Word[];
+  readonly walkerState: Readonly<WhenWalkerState>;
+}
+
+/**
+ * Prepare bash state for every rule to share: parse once, extract +
+ * expand wrappers once, walk trackers once, stringify each ref once.
+ *
+ * Also runs the walker-level speculative-entry synthesis pass and
+ * merges its output into each ref's walkerState under the reserved
+ * `events` key. The built-in `when.happened` predicate consults
+ * `ctx.walkerState.events[customType]` to unify real + speculative
+ * entries via timestamp ordering (see {@link evaluateHappened}).
+ */
+function prepareBashState(
+  command: string,
+  sessionCwd: string,
+  trackers: Record<string, Tracker<unknown>>,
+  observers: readonly Observer[],
+): BashRefState[] {
+  const script = parseBash(command);
+  const extracted = extractAllCommandsFromAST(script, command);
+  const { commands: refs } = expandWrapperCommands(extracted);
+  const walkResult = walk(
+    script,
+    { cwd: sessionCwd } as Record<string, unknown>,
+    trackers,
+    refs,
+  );
+  const speculativeEvents: SpeculativeEventsByRef =
+    synthesizeSpeculativeEntries(refs, observers);
+  return refs.map((ref) => {
+    const trackerState = walkResult.get(ref) ?? {
+      cwd: sessionCwd,
+      env: new Map<string, string>(),
+    };
+    const events = speculativeEvents.get(ref) ?? {};
+    return {
+      ref,
+      text: refToText(ref),
+      basename: getBasename(ref),
+      // `node.suffix` is the quote-aware Word[] for the ref. Exposed
+      // to predicates via PredicateToolInput.args; the walker already
+      // parsed it so we just pass it through.
+      args: ref.node.suffix,
+      // `node.prefix` is unbash's AssignmentPrefix[] (shape:
+      // `{ text, name, value, ... }`). Project into Word[] so
+      // PredicateToolInput.envAssignments lines up with `.args` for
+      // plugin consumers — `.text` preserves the full "KEY=VALUE"
+      // source token (with quoting), and dynamic values like `A=$VAR`
+      // come through visibly in `.text` so callers can detect them.
+      envAssignments: ref.node.prefix.map<Word>((p) => ({
+        text: p.text,
+        value: p.text,
+        pos: p.pos,
+        end: p.end,
+      })),
+      // Merge tracker state with synthesized events so the built-in
+      // `happened` predicate can read `walkerState.events` without
+      // threading a separate context field. Trackers cannot name a
+      // dimension `"events"` — the plugin merger rejects that (see
+      // plugin-merger.ts). The merge is a shallow copy so the walker's
+      // state object stays untouched for future evaluations.
+      //
+      // The cast via `unknown` to `Readonly<WhenWalkerState>` is safe:
+      // buildEvaluator always registers `cwd` + `env` trackers, so every
+      // ref the walker yields carries both fields; the fallback literal
+      // above also supplies them. The schema interface's `readonly
+      // [key: string]: unknown` index signature tolerates the `events`
+      // key and any plugin-registered tracker slot. TypeScript's
+      // spread inference over `Record<string, unknown> | { cwd: string;
+      // env: Map<...> }` doesn't preserve the cwd/env shape through
+      // the spread, so the double cast is the minimum TS needs to
+      // accept a structure its inference widens away.
+      walkerState: {
+        ...trackerState,
+        events,
+      } as unknown as Readonly<WhenWalkerState>,
+    };
+  });
+}
+
+/**
+ * Compute the effective `noOverride` for a rule — rule-level explicit
+ * value wins, falling back to the config-level default (itself defaulted
+ * to fail-closed `true` per ADR).
+ */
+function effectiveNoOverride(rule: Rule, defaultNoOverride: boolean): boolean {
+  return rule.noOverride ?? defaultNoOverride;
+}
+
+/**
+ * Format the block reason shown to the agent. Appends an override hint
+ * ONLY when the rule is overridable — rules with
+ * `noOverride: true` (or the fail-closed default) omit it to avoid
+ * advertising a nonexistent escape hatch.
+ *
+ * Source-tagged (per ADR §11): `[steering:<rule-name>@<source>] …`
+ * where `<source>` is the originating plugin name for plugin-shipped
+ * rules, or `user` for rules declared directly in the user's
+ * SteeringConfig.rules.
+ *
+ * Rule.reason accepts both a static string and a {@link ReasonFn}
+ * (D3 in pr5-tier-b-shell-var-tracker-spec.md). Function reasons
+ * receive the same {@link PredicateContext} the predicates saw;
+ * async returns are awaited before prefixing. A reason function
+ * that throws or rejects is logged via `console.warn` and replaced
+ * with a fail-safe fallback string — the block verdict still fires.
+ * The exact fallback text is a stable contract rule authors can
+ * detect in tests.
+ *
+ * Tag→body separator is paragraph-aware: when the resolved body
+ * contains a `\n\n` paragraph break, the tag is rendered on its own
+ * line (`${tag}\n\n${body}`) so subsequent paragraphs don't orphan
+ * visually from the source-tag prefix. Single-paragraph bodies keep
+ * the legacy single-space layout (`${tag} ${body}`) — backward-
+ * compatible for every reason that was single-paragraph before the
+ * paragraph-aware rendering shipped. Trigger is `\n\n` or its CRLF
+ * equivalent `\r\n\r\n` (defensive against bodies imported from
+ * Windows line-ending sources — CRLF templating layers, hand-typed
+ * Windows-IDE strings); a single `\n` inside an otherwise single-
+ * paragraph body keeps the single-space layout. The emitted
+ * separator is always normalized to `\n\n` regardless of which form
+ * triggered it.
+ *
+ * Body→override-hint separator mirrors the same paragraph-aware
+ * separator. Single-paragraph bodies keep the single-space prefix
+ * on the override hint (byte-identical to the pre-paragraph-aware
+ * rendering); multi-paragraph bodies promote the override hint to
+ * its own paragraph (`${body}\n\n${hint}`) so the safety paragraph
+ * stays visually standalone rather than running on into an inline
+ * "To override" sentence. Mirror docs on {@link Rule.reason}.
+ */
+async function formatReason(
+  rule: Rule,
+  tool: "bash" | "write" | "edit",
+  noOverride: boolean,
+  source: string,
+  ctx: PredicateContext,
+): Promise<string> {
+  const tag = `[steering:${rule.name}@${source}]`;
+  const body = await resolveReasonBody(rule, source, ctx);
+  // Paragraph-aware tag separator — see function-level JSDoc for the
+  // contract; this line implements the trigger detection.
+  const multiPara = body.includes("\n\n") || body.includes("\r\n\r\n");
+  const separator = multiPara ? "\n\n" : " ";
+  if (noOverride) return `${tag}${separator}${body}`;
+  const leader = tool === "bash" ? "#" : "//";
+  const hint =
+    `To override, include a comment: ` +
+    `\`${leader} steering-override: ${rule.name} — <reason>\`.`;
+  return `${tag}${separator}${body}${separator}${hint}`;
+}
+
+/**
+ * Resolve the string body of a rule's reason field. Handles both
+ * variants of the discriminated union on {@link Rule.reason}:
+ *
+ *   - `string`        — returned as-is.
+ *   - `ReasonFn`      — invoked with `ctx`, awaited, returned. A
+ *                       synchronous throw or rejected promise is
+ *                       caught, logged to `console.warn` with the
+ *                       rule name + source prefix + error message
+ *                       + stack, and replaced with the fail-safe
+ *                       fallback body `(reason failed to format;
+ *                       see log)`. The wrapping in
+ *                       {@link formatReason} still adds the source
+ *                       tag, so the agent sees
+ *                       `[steering:<rule>@<source>] (reason failed
+ *                       to format; see log)` — an unambiguous
+ *                       signal of a broken reason fn that still
+ *                       doesn't leak the error message.
+ *
+ * The fallback behavior is part of the public contract per spec
+ * D3: a rule author CAN assert the exact text (e.g. in a test
+ * asserting the engine keeps the block verdict alive when the
+ * reason function intentionally throws as a smoke-test).
+ */
+async function resolveReasonBody(
+  rule: Rule,
+  source: string,
+  ctx: PredicateContext,
+): Promise<string> {
+  if (typeof rule.reason === "string") return rule.reason;
+  try {
+    return await rule.reason(ctx);
+  } catch (err) {
+    const msg =
+      err instanceof Error ? `${err.message}\n${err.stack ?? ""}` : String(err);
+    console.warn(
+      `[pi-steering] Rule "${rule.name}"@${source}: reason function threw: ${msg}`,
+    );
+    return "(reason failed to format; see log)";
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Unified per-candidate evaluation
+// ---------------------------------------------------------------------------
+
+/**
+ * Per-tool_call state shared across every candidate and rule. One
+ * struct in place of the 6-argument bundle the prior shape threaded
+ * through both bash and write/edit call-sites.
+ *
+ * `exec` / `appendEntry` / `findEntries` are the closures the evaluator
+ * builds once per tool_call (see `./evaluator-internals/context.ts`).
+ * `appendEntry` auto-tags every write with the current
+ * `_agentLoopIndex`, including the `steering-override` audit entries
+ * written from the override-accepted path — so rules using
+ * `when.happened: { event: "steering-override", in: "agent_loop" }`
+ * can correctly filter override activity to the current agent loop.
+ *
+ * `host` is retained on the shared context for non-entry operations
+ * (currently only `exec` indirectly) and for tests that stub pi’s
+ * surface without having to re-shape every call-site.
+ */
+interface SharedEvalContext {
+  readonly agentLoopIndex: number;
+  readonly predicates: ResolvedPluginState["predicates"];
+  readonly exec: PredicateContext["exec"];
+  readonly appendEntry: PredicateContext["appendEntry"];
+  readonly findEntries: PredicateContext["findEntries"];
+  readonly host: EvaluatorHost;
+  readonly defaultNoOverride: boolean;
+  /**
+   * Rule → source-name lookup for source-tagged block reasons
+   * (`[steering:<rule>@<source>]`). Keyed by Rule object identity so
+   * the same rule name appearing in multiple plugins still resolves
+   * unambiguously.
+   */
+  readonly ruleSources: ReadonlyMap<Rule, string>;
+}
+
+/**
+ * Single-candidate input for {@link evaluateCandidate}. The fields here
+ * are the sole per-tool axes of variation — the body of
+ * `evaluateCandidate` stays tool-agnostic.
+ *
+ *   - `target`        — string the rule's `pattern` / `requires` /
+ *                        `unless` test against (bash: basename + args
+ *                        for the current ref; write: content or path;
+ *                        edit: joined newText or path).
+ *   - `cwd`           — effective cwd seen by predicates via
+ *                        `ctx.cwd`. Per-ref for bash (walker-resolved);
+ *                        session cwd for write / edit.
+ *   - `input`         — the `PredicateToolInput` predicates see via
+ *                        `ctx.input`.
+ *   - `overrideCarrier` — text scanned for `# steering-override: …`
+ *                          comments. Bash: the raw tool_call command;
+ *                          write: content; edit: joined newText.
+ *   - `tool`          — plain-string tool, drives the override-comment
+ *                        leader (`#` vs `//`) and the block reason.
+ *   - `overrideEntryExtras` — extra fields merged into the
+ *                              `steering-override` audit entry
+ *                              (`command` for bash, `path` for
+ *                              write / edit).
+ */
+interface Candidate {
+  readonly target: string;
+  readonly cwd: string;
+  readonly input: PredicateToolInput;
+  readonly overrideCarrier: string;
+  readonly tool: "bash" | "write" | "edit";
+  readonly overrideEntryExtras: Record<string, string>;
+  /**
+   * Walker state snapshot for this candidate. Bash candidates carry
+   * the per-ref walk result (including synthesized
+   * `events: Record<customType, SyntheticEntry[]>` under the reserved
+   * `events` key, populated by the walker-level speculative-entry
+   * synthesis pass); write / edit candidates leave it undefined (no
+   * walker ran).
+   */
+  readonly walkerState?: Readonly<WhenWalkerState>;
+}
+
+/**
+ * Outcome of `evaluateCandidate`:
+ *   - {@link ToolCallEventResult}  — rule fired + was NOT overridden.
+ *                                     Caller returns this to stop
+ *                                     evaluation for the whole event.
+ *   - `"no-fire"`                   — rule didn't match this candidate.
+ *                                     Caller continues to the next
+ *                                     candidate (bash) or next rule
+ *                                     (write / edit).
+ *   - `"overridden"`                — rule fired but an override comment
+ *                                     was accepted + audit-logged.
+ *                                     Caller moves to the next rule;
+ *                                     for bash that also means stopping
+ *                                     the ref loop (override covers the
+ *                                     whole tool_call per v1 semantics).
+ */
+type CandidateOutcome = ToolCallEventResult | "no-fire" | "overridden";
+
+/**
+ * Run a rule's predicate chain (pattern → requires → unless → when).
+ * Returns the built {@link PredicateContext} when every predicate
+ * passes (rule fires), or `null` when the chain short-circuits to
+ * "no-fire" — **either** because a predicate legitimately rejected
+ * the candidate, **or** because a predicate threw.
+ *
+ * Throws are the S1 hardening: a predicate function (built-in or
+ * plugin-supplied) that throws synchronously or rejects asynchronously
+ * gets its error logged with the rule name + source and the rule is
+ * treated as NOT firing. Evaluation continues with the next rule.
+ *
+ * Why "does not fire" (vs "block" / "abort the whole evaluate"):
+ *   - Mirrors the observer-dispatcher's per-observer isolation —
+ *     one broken predicate must not poison the rest of the rule list.
+ *   - A buggy predicate blocking everything would be worse UX than
+ *     a buggy predicate silently failing — the block reason would
+ *     leak the raw error message to the LLM (the pre-hardening
+ *     behaviour). Top-level engine-throws still fail CLOSED; see
+ *     {@link evaluateEvent}.
+ */
+async function runPredicateChain(
+  rule: Rule,
+  cand: Candidate,
+  shared: SharedEvalContext,
+): Promise<PredicateContext | null> {
+  const source = shared.ruleSources.get(rule) ?? "user";
+  try {
+    // Pattern-miss is the common case; exit before allocating ctx.
+    if (!matchesPattern(rule.pattern, cand.target)) return null;
+
+    const ctx: PredicateContext = {
+      cwd: cand.cwd,
+      tool: cand.tool,
+      input: cand.input,
+      agentLoopIndex: shared.agentLoopIndex,
+      exec: shared.exec,
+      appendEntry: shared.appendEntry,
+      findEntries: shared.findEntries,
+      ...(cand.walkerState !== undefined
+        ? { walkerState: cand.walkerState }
+        : {}),
+    };
+
+    if (rule.requires !== undefined) {
+      const ok = await matchesPatternOrFn(rule.requires, cand.target, ctx);
+      if (!ok) return null;
+    }
+    if (rule.unless !== undefined) {
+      const ok = await matchesPatternOrFn(rule.unless, cand.target, ctx);
+      if (ok) return null;
+    }
+    const whenOk = await evaluateWhen(
+      rule.when,
+      { cwd: cand.cwd },
+      ctx,
+      shared.predicates,
+      rule.name,
+      source,
+    );
+    if (!whenOk) return null;
+
+    return ctx;
+  } catch (err) {
+    console.warn(
+      `[pi-steering] predicate threw for rule "${rule.name}"@${source}: ${formatError(err)}`,
+    );
+    return null;
+  }
+}
+
+/**
+ * Evaluate one candidate against one rule. This is the single pipeline
+ * every tool funnels through — differences between bash, write, and
+ * edit live entirely in the {@link Candidate} input.
+ *
+ * Evaluation order (short-circuits on first failure):
+ *
+ *   1. `pattern`   — required; if no match we exit before allocating
+ *                     the predicate context.
+ *   2. `requires`  — optional AND.
+ *   3. `unless`    — optional exemption.
+ *   4. `when`      — clause tree (`cwd`, `not`, `condition`, plugin
+ *                     predicates).
+ *
+ * All four steps are wrapped in a try/catch via
+ * {@link runPredicateChain} — a throw is logged and treated as "rule
+ * did not fire". That way a buggy predicate neither short-circuits the
+ * whole rule list (a broken guardrail rule silently poisoning the
+ * rest) nor leaks its raw `error.message` back to the agent via a
+ * pi-level error tool_result.
+ *
+ * On rule fire, check for an override comment addressing the rule by
+ * name (unless the rule opts out of overrides). An accepted override
+ * logs a `steering-override` audit entry and returns `"overridden"`.
+ */
+async function evaluateCandidate(
+  rule: Rule,
+  cand: Candidate,
+  shared: SharedEvalContext,
+): Promise<CandidateOutcome> {
+  const ctx = await runPredicateChain(rule, cand, shared);
+  if (ctx === null) return "no-fire";
+
+  // Rule fires. Check for override (if allowed) before committing to
+  // blocking.
+  const noOverride = effectiveNoOverride(rule, shared.defaultNoOverride);
+  if (!noOverride) {
+    const reason = extractOverride(cand.overrideCarrier, rule.name);
+    if (reason !== null) {
+      // Go through the wrapped `shared.appendEntry` so the
+      // `_agentLoopIndex` auto-tag lands on the audit entry. Rules
+      // using `when.happened: { event: "steering-override", in:
+      // "agent_loop" }` rely on the tag to filter overrides by the
+      // current loop; a direct `host.appendEntry` here would bypass
+      // the wrapper and leave the entry invisible to that predicate.
+      shared.appendEntry("steering-override", {
+        rule: rule.name,
+        reason,
+        ...cand.overrideEntryExtras,
+        timestamp: new Date().toISOString(),
+      });
+      return "overridden";
+    }
+  }
+
+  // Block is going to fire. Run the optional side-effect hook before
+  // returning the verdict — rules using `onFire` to self-mark (e.g.
+  // "write a session entry so my next attempt this agent loop passes")
+  // need the write to land before the agent sees the block. Override
+  // paths above already returned, so onFire is skipped when the rule
+  // was overridden; fail-closed defaults with no override comment fall
+  // through here normally.
+  //
+  // Fail-closed semantics on onFire errors: a sync throw or rejected
+  // promise is logged and SWALLOWED — the block still returns. The
+  // block decision already passed every predicate; a broken
+  // best-effort side effect must not silently invalidate it. Mirrors
+  // the observer-dispatcher's per-observer try/catch (observers are
+  // isolated for the same reason).
+  if (rule.onFire) {
+    try {
+      await rule.onFire(ctx);
+    } catch (err) {
+      console.warn(
+        `[pi-steering] onFire for rule "${rule.name}" threw: ${formatError(err)}`,
+      );
+    }
+  }
+
+  return {
+    block: true,
+    reason: await formatReason(
+      rule,
+      cand.tool,
+      noOverride,
+      shared.ruleSources.get(rule) ?? "user",
+      ctx,
+    ),
+  };
+}
+
+async function evaluateEvent(
+  event: ToolCallEvent,
+  ctx: ExtensionContext,
+  agentLoopIndex: number,
+  rules: readonly Rule[],
+  trackers: Record<string, Tracker<unknown>>,
+  predicates: ResolvedPluginState["predicates"],
+  host: EvaluatorHost,
+  defaultNoOverride: boolean,
+  ruleSources: ReadonlyMap<Rule, string>,
+  allObservers: readonly Observer[],
+): Promise<ToolCallEventResult | void> {
+  // Top-level fail-closed wrap (S1). If the engine's own scaffolding
+  // throws — parse errors, walker bugs, corrupted session JSONL, etc.
+  // — we block the tool AS A SAFETY MEASURE and tag the reason so the
+  // agent sees it came from the engine, not from a rule or plugin.
+  // Per-predicate throws are handled one level down in
+  // {@link runPredicateChain} (treated as "rule does not fire"); this
+  // outer wrap only catches throws OUTSIDE the per-rule try/catch.
+  try {
+    return await evaluateEventInner(
+      event,
+      ctx,
+      agentLoopIndex,
+      rules,
+      trackers,
+      predicates,
+      host,
+      defaultNoOverride,
+      ruleSources,
+      allObservers,
+    );
+  } catch (err) {
+    console.error(`[pi-steering] steering engine threw: ${formatError(err)}`);
+    return {
+      block: true,
+      reason:
+        "[steering:engine@internal] steering engine error; " +
+        "tool blocked as a safety measure",
+    };
+  }
+}
+
+async function evaluateEventInner(
+  event: ToolCallEvent,
+  ctx: ExtensionContext,
+  agentLoopIndex: number,
+  rules: readonly Rule[],
+  trackers: Record<string, Tracker<unknown>>,
+  predicates: ResolvedPluginState["predicates"],
+  host: EvaluatorHost,
+  defaultNoOverride: boolean,
+  ruleSources: ReadonlyMap<Rule, string>,
+  allObservers: readonly Observer[],
+): Promise<ToolCallEventResult | void> {
+  // Shared per-call closures: exec memoized by (cmd, args, cwd);
+  // findEntries reads the current session JSONL on demand; appendEntry
+  // auto-tags writes with `_agentLoopIndex` so rules using
+  // `when.happened` can filter by agent-loop scope.
+  //
+  // findEntries + appendEntry share a session-entry cache so a write
+  // performed by an earlier rule's onFire (or by the override-audit
+  // path) invalidates the cached read — later rules' when.happened
+  // predicates see the fresh write instead of a stale snapshot
+  // (S2/E1). The evaluator itself doesn't interleave writes with reads,
+  // but onFire + override-audit do.
+  const exec = createExecCache(host, ctx.cwd);
+  const entryCache = createSessionEntryCache();
+  const findEntries = createFindEntries(ctx, entryCache);
+  const appendEntry = createAppendEntry(host, agentLoopIndex, entryCache);
+
+  const shared: SharedEvalContext = {
+    agentLoopIndex,
+    predicates,
+    exec,
+    appendEntry,
+    findEntries,
+    host,
+    defaultNoOverride,
+    ruleSources,
+  };
+
+  // Bash state is lazy: non-bash rules don't pay for parse / walk.
+  let bashState: BashRefState[] | null = null;
+  const bashEvent = isToolCallEventType("bash", event) ? event : null;
+
+  // Edit events share `allNewText` across every field="content" rule.
+  // Computed lazily on the first edit rule so a config with only bash /
+  // write rules doesn't pay the join cost. `null` sentinel is safe
+  // because `edits` is always a non-null array on edit events.
+  const editEvent = isToolCallEventType("edit", event) ? event : null;
+  let editAllNewText: string | null = null;
+
+  for (const rule of rules) {
+    if (rule.tool !== event.toolName) continue;
+
+    if (rule.tool === "bash") {
+      if (!bashEvent) continue;
+      if (bashState === null) {
+        bashState = prepareBashState(
+          bashEvent.input.command,
+          ctx.cwd,
+          trackers,
+          allObservers,
+        );
+      }
+      const result = await evaluateBashRule(
+        rule,
+        bashEvent.input.command,
+        bashState,
+        shared,
+      );
+      if (result !== undefined) return result;
+      continue;
+    }
+
+    if (rule.tool === "write" && isToolCallEventType("write", event)) {
+      const target =
+        rule.field === "path" ? event.input.path : event.input.content;
+      const result = await evaluateWriteEditRule(
+        rule,
+        {
+          tool: "write",
+          path: event.input.path,
+          content: event.input.content,
+          // Shell env assignments don't apply to file-surface tools;
+          // shape as `[]` rather than `undefined` so plugin authors
+          // can treat the field uniformly across tools.
+          envAssignments: [],
+        },
+        target,
+        // override-comment scanned against content (the natural
+        // carrier for write override comments — v1 parity).
+        event.input.content,
+        event.input.path,
+        ctx.cwd,
+        shared,
+      );
+      if (result !== undefined) return result;
+      continue;
+    }
+
+    if (rule.tool === "edit" && editEvent) {
+      // Joined newText is needed as override carrier for EVERY edit
+      // rule plus as `target` for field="content" rules. Compute once
+      // per tool_call on the first edit rule, reuse for the rest.
+      if (editAllNewText === null) {
+        editAllNewText = editEvent.input.edits.map((e) => e.newText).join("\n");
+      }
+      const target =
+        rule.field === "path" ? editEvent.input.path : editAllNewText;
+      const result = await evaluateWriteEditRule(
+        rule,
+        {
+          tool: "edit",
+          path: editEvent.input.path,
+          edits: editEvent.input.edits,
+          // See the write branch above: `[]` for uniform shape.
+          envAssignments: [],
+        },
+        target,
+        editAllNewText,
+        editEvent.input.path,
+        ctx.cwd,
+        shared,
+      );
+      if (result !== undefined) return result;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Per-rule bash evaluation. Iterates every extracted command ref as
+ * a {@link Candidate}. The first ref that fires the rule (pattern +
+ * requires + unless + when) decides the verdict. Per v1 semantics, an
+ * accepted override covers the whole tool_call — we stop scanning
+ * further refs and hand control back to the caller.
+ */
+async function evaluateBashRule(
+  rule: Rule,
+  rawCommand: string,
+  state: BashRefState[],
+  shared: SharedEvalContext,
+): Promise<ToolCallEventResult | void> {
+  for (const refState of state) {
+    const cand: Candidate = {
+      target: refState.text,
+      cwd:
+        typeof refState.walkerState["cwd"] === "string"
+          ? (refState.walkerState["cwd"] as string)
+          : "unknown",
+      input: {
+        tool: "bash",
+        command: refState.text,
+        basename: refState.basename,
+        args: refState.args,
+        envAssignments: refState.envAssignments,
+      },
+      overrideCarrier: rawCommand,
+      tool: "bash",
+      overrideEntryExtras: { command: rawCommand },
+      walkerState: refState.walkerState,
+    };
+    const r = await evaluateCandidate(rule, cand, shared);
+    if (r === "no-fire") continue;
+    if (r === "overridden") return undefined; // v1: override covers whole tool_call
+    return r;
+  }
+  return undefined;
+}
+
+/**
+ * Per-rule write / edit evaluation. Produces a single {@link Candidate}
+ * and defers to {@link evaluateCandidate}.
+ *
+ * `target` is the pre-resolved string the rule's pattern tests against
+ * — the caller computes it once per rule (reading `path` or the joined
+ * `newText`), which lets edit tool_calls share the join across every
+ * field="content" rule. `overrideCarrier` is the text scanned for
+ * override comments (per v1 parity, content / joined newText even for
+ * field="path" rules).
+ */
+async function evaluateWriteEditRule(
+  rule: Rule,
+  input: PredicateToolInput,
+  target: string,
+  overrideCarrier: string,
+  path: string,
+  sessionCwd: string,
+  shared: SharedEvalContext,
+): Promise<ToolCallEventResult | void> {
+  const cand: Candidate = {
+    target,
+    cwd: sessionCwd,
+    input,
+    overrideCarrier,
+    tool: rule.tool as "write" | "edit",
+    overrideEntryExtras: { path },
+  };
+  const r = await evaluateCandidate(rule, cand, shared);
+  if (r === "no-fire" || r === "overridden") return undefined;
+  return r;
+}
+
+// ---------------------------------------------------------------------------
+// Error formatting
+// ---------------------------------------------------------------------------
+
+/**
+ * Format an unknown thrown value for a warning log. Shared across the
+ * three places the evaluator catches throws:
+ *
+ *   - per-predicate try/catch in {@link runPredicateChain} (S1).
+ *   - per-rule `onFire` try/catch in {@link evaluateCandidate}.
+ *   - top-level engine try/catch in {@link evaluateEvent}.
+ *
+ * Mirrors the observer-dispatcher's `formatError` so the log shape
+ * stays consistent across the two hook surfaces: `message\nstack` for
+ * proper Errors, best-effort JSON otherwise, falling through to
+ * `String(err)`.
+ */
+function formatError(err: unknown): string {
+  if (err instanceof Error) return `${err.message}\n${err.stack ?? ""}`;
+  try {
+    return JSON.stringify(err);
+  } catch {
+    return String(err);
+  }
+}
+
+// Re-export supporting types for consumers embedding the evaluator.
+export type { EvaluatorHost } from "./evaluator-internals/context.ts";