@cad0p/pi-steering 0.1.0

package/dist/evaluator.js

@@ -0,0 +1,714 @@
+// SPDX-License-Identifier: MIT
+// Part of pi-steering.
+import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
+import { cwdTracker, envTracker, expandWrapperCommands, extractAllCommandsFromAST, getBasename, parse as parseBash, walk, } from "@cad0p/unbash-walker";
+import { createAppendEntry, createExecCache, createFindEntries, createSessionEntryCache, } from "./evaluator-internals/context.js";
+import { extractOverride } from "./evaluator-internals/override.js";
+import { evaluateWhen, matchesPattern, matchesPatternOrFn, validateWhenClauseShape, } from "./evaluator-internals/predicates.js";
+import { synthesizeSpeculativeEntries, } from "./evaluator-internals/speculative-synthesis.js";
+import { mergeObserversUserFirst } from "./internal/merge-observers.js";
+import { refToText } from "./internal/ref-text.js";
+import { validateName } from "./plugin-merger.js";
+// ---------------------------------------------------------------------------
+// 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"];
+/**
+ * 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, resolved, host) {
+    // 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 = [...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();
+    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 = {
+        ...resolved.composedTrackers,
+    };
+    if (!("env" in trackers)) {
+        const extraEnvModifiers = resolved.trackerModifiers["env"];
+        trackers["env"] = composeBuiltinEnv(extraEnvModifiers);
+    }
+    if (!("cwd" in trackers)) {
+        const extraCwdModifiers = resolved.trackerModifiers["cwd"];
+        trackers["cwd"] = composeBuiltinCwd(extraCwdModifiers);
+    }
+    // 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) {
+    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) {
+    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(baseTracker, extras) {
+    if (!extras || Object.keys(extras).length === 0)
+        return baseTracker;
+    const merged = {};
+    for (const [basename, mod] of Object.entries(baseTracker.modifiers)) {
+        merged[basename] = Array.isArray(mod) ? [...mod] : mod;
+    }
+    for (const [basename, mods] of Object.entries(extras)) {
+        const existing = merged[basename];
+        const extrasTyped = mods;
+        if (existing === undefined) {
+            merged[basename] =
+                extrasTyped.length === 1 ? extrasTyped[0] : [...extrasTyped];
+            continue;
+        }
+        const existingList = Array.isArray(existing)
+            ? existing
+            : [existing];
+        merged[basename] = [...existingList, ...extrasTyped];
+    }
+    return { ...baseTracker, modifiers: merged };
+}
+/**
+ * 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, sessionCwd, trackers, observers) {
+    const script = parseBash(command);
+    const extracted = extractAllCommandsFromAST(script, command);
+    const { commands: refs } = expandWrapperCommands(extracted);
+    const walkResult = walk(script, { cwd: sessionCwd }, trackers, refs);
+    const speculativeEvents = synthesizeSpeculativeEntries(refs, observers);
+    return refs.map((ref) => {
+        const trackerState = walkResult.get(ref) ?? {
+            cwd: sessionCwd,
+            env: new Map(),
+        };
+        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((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,
+            },
+        };
+    });
+}
+/**
+ * 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, defaultNoOverride) {
+    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, tool, noOverride, source, ctx) {
+    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, source, ctx) {
+    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)";
+    }
+}
+/**
+ * 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, cand, shared) {
+    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 = {
+            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, cand, shared) {
+    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, ctx, agentLoopIndex, rules, trackers, predicates, host, defaultNoOverride, ruleSources, allObservers) {
+    // 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, ctx, agentLoopIndex, rules, trackers, predicates, host, defaultNoOverride, ruleSources, allObservers) {
+    // 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 = {
+        agentLoopIndex,
+        predicates,
+        exec,
+        appendEntry,
+        findEntries,
+        host,
+        defaultNoOverride,
+        ruleSources,
+    };
+    // Bash state is lazy: non-bash rules don't pay for parse / walk.
+    let bashState = 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 = 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, rawCommand, state, shared) {
+    for (const refState of state) {
+        const cand = {
+            target: refState.text,
+            cwd: typeof refState.walkerState["cwd"] === "string"
+                ? refState.walkerState["cwd"]
+                : "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, input, target, overrideCarrier, path, sessionCwd, shared) {
+    const cand = {
+        target,
+        cwd: sessionCwd,
+        input,
+        overrideCarrier,
+        tool: rule.tool,
+        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) {
+    if (err instanceof Error)
+        return `${err.message}\n${err.stack ?? ""}`;
+    try {
+        return JSON.stringify(err);
+    }
+    catch {
+        return String(err);
+    }
+}
+//# sourceMappingURL=evaluator.js.map