vigiles 15.0.3 → 15.2.0

package/dist/cli.js

@@ -59,6 +59,7 @@ const merge_conflict_js_1 = require("./core/merge-conflict.js");
 const hook_install_js_1 = require("./hook-install.js");
 const hook_providers_js_1 = require("./core/hook-providers.js");
 const toml_1 = require("@iarna/toml");
+const hash_js_1 = require("./core/hash.js");
 const agent_runtime_js_1 = require("./adapters/claude-code/agent-runtime.js");
 const observe_js_1 = require("./observe.js");
 const effect_region_js_1 = require("./adapters/claude-code/effect-region.js");
@@ -5016,6 +5017,84 @@ async function compileProviders() {
 function hookStampPath(file) {
     return (0, node_path_1.resolve)(process.cwd(), ".vigiles/hooks", (0, node_path_1.basename)(file) + ".json");
 }
+/**
+ * The directory a hook's recorded facts live in — the SCOPE of `state()`/`record()`.
+ *
+ * Derived from the hook's own location and never from anything the hook said, so
+ * a key cannot address another owner's store: hooks shipped in the same directory
+ * share their facts (the requirement — one hook records, another reads), a
+ * vendored plugin's hooks get their own. The layout MIRRORS the hook's directory
+ * rather than slugging it, which keeps it injective and lets a human debugging a
+ * hook find the fact by walking the path they already know:
+ *
+ *   .claude/hooks/calendar-sync-record.hook.ts
+ *     → .vigiles/state/.claude/hooks/calendar.synced.json
+ *
+ * A hook outside the project (an absolute path elsewhere) falls back to a hash of
+ * its directory: still stable and still isolated, just not readable — which is the
+ * right trade for a case that should not happen in a project's own harness.
+ */
+function hookStateDir(file) {
+    const dir = (0, node_path_1.dirname)((0, node_path_1.resolve)(process.cwd(), file));
+    const rel = (0, node_path_1.relative)(process.cwd(), dir);
+    const inside = rel !== "" && !rel.startsWith("..") && !(0, node_path_1.isAbsolute)(rel);
+    return (0, node_path_1.resolve)(process.cwd(), ".vigiles/state", inside ? rel : `external-${(0, hash_js_1.sha256short)(dir)}`);
+}
+/** Read one recorded fact for a hook, or `null` if it was never recorded. */
+function readHookState(file, key) {
+    try {
+        const raw = (0, node_fs_1.readFileSync)((0, node_path_1.resolve)(hookStateDir(file), key + ".json"), "utf-8");
+        const parsed = JSON.parse(raw);
+        return typeof parsed.value === "string" && typeof parsed.at === "string"
+            ? parsed
+            : null;
+    }
+    catch {
+        // Never recorded, unreadable, or corrupt — all "no fact", which `stateFact`
+        // turns into an infinite age, so the reading hook SPEAKS. Failing toward
+        // noise is the whole point; a store problem must never look like freshness.
+        return null;
+    }
+}
+/**
+ * Record one fact. Atomic: written to a temp file in the same directory and
+ * `rename()`d over, so a concurrent reader sees the whole old entry or the whole
+ * new one — never one write's value with another's timestamp. Distinct keys are
+ * distinct files and never interact at all.
+ */
+function writeHookState(file, w) {
+    const dir = hookStateDir(file);
+    const target = (0, node_path_1.resolve)(dir, w.name + ".json");
+    const entry = {
+        value: w.value,
+        at: new Date().toISOString(),
+        by: (0, hook_install_js_1.normalizeHookRef)(file),
+    };
+    (0, node_fs_1.mkdirSync)(dir, { recursive: true });
+    const tmp = `${target}.${String(process.pid)}.tmp`;
+    (0, node_fs_1.writeFileSync)(tmp, JSON.stringify(entry, null, 2) + "\n");
+    (0, node_fs_1.renameSync)(tmp, target);
+}
+/**
+ * Perform the state writes a hook declared, after its output has been emitted.
+ * A refused write (a hand-built record object with a key `record()` would have
+ * thrown on) is announced — silence here would be a hook that believes it
+ * remembered something.
+ */
+function applyHookWrites(file, outcome) {
+    const { ok, refused } = (0, hook_program_js_1.outcomeWrites)(outcome);
+    for (const name of refused) {
+        console.error(`vigiles: refused to record ${name} from ${file} — not a valid state key.`);
+    }
+    for (const w of ok) {
+        try {
+            writeHookState(file, w);
+        }
+        catch (e) {
+            console.error(`vigiles: could not record ${w.name} from ${file}: ${String(e)}`);
+        }
+    }
+}
 /**
  * Compile ONE typed hook program (authored against `vigiles/hook`) and MERGE it
  * into the active harness's native config — the hook half of `vigiles compile`
@@ -5168,7 +5247,7 @@ async function installHooks(hookFiles, harnessFlag, configHarness) {
  * that can't resolve yields its default (never throws). The pure registry +
  * decision logic live in core/hook-providers.ts — this only injects the real IO.
  */
-async function gatherHookContext(program) {
+async function gatherHookContext(program, file) {
     const needs = (0, hook_program_js_1.hookNeeds)(program);
     if (needs.length === 0)
         return {};
@@ -5185,6 +5264,10 @@ async function gatherHookContext(program) {
         cwd: process.cwd(),
         platform: process.platform,
         isCI,
+        // The namespace is bound HERE, from the hook's own path — core never sees
+        // it, so no key a hook can spell reaches another owner's store.
+        readState: (key) => readHookState(file, key),
+        now: Date.now(),
     }, registry);
 }
 /**
@@ -5498,13 +5581,30 @@ async function runHookProgramCommand(file) {
     verifyStampOrRefuse(file, event);
     switch ((0, hook_program_js_1.dispatchKind)(program)) {
         case "inject": {
-            const out = (0, hook_program_js_1.runInject)(program, { source: event.source });
-            process.stdout.write(JSON.stringify(out) + "\n");
+            const ctx = await gatherHookContext(program, file);
+            const injection = (0, hook_program_js_1.injectionOf)(program, event, ctx);
+            process.stdout.write(JSON.stringify({
+                hookSpecificOutput: {
+                    hookEventName: program.on,
+                    additionalContext: injection.context,
+                },
+            }) + "\n");
+            // Writes land AFTER the output is emitted: a hook that recorded "I spoke"
+            // must not have recorded it if emitting threw.
+            applyHookWrites(file, {
+                kind: "injection",
+                context: injection.context,
+                records: injection.records,
+            });
             return;
         }
         case "react": {
+            const ctx = await gatherHookContext(program, file);
             warnIfPathUndecidable(event, projectRoot);
-            const reaction = (0, hook_program_js_1.runReact)(program, event, projectRoot);
+            const reaction = (0, hook_program_js_1.runReact)(program, event, ctx, projectRoot);
+            if (reaction.kind === "notice")
+                console.error(reaction.message);
+            applyHookWrites(file, { kind: "reaction", reaction });
             if (reaction.kind === "run") {
                 const { spawnSync } = require("node:child_process");
                 const res = spawnSync(reaction.command, {
@@ -5513,18 +5613,16 @@ async function runHookProgramCommand(file) {
                 });
                 process.exit(res.status ?? 0);
             }
-            if (reaction.kind === "notice")
-                console.error(reaction.message);
             return;
         }
         case "file-gate": {
-            const ctx = await gatherHookContext(program);
+            const ctx = await gatherHookContext(program, file);
             warnIfPathUndecidable(event, projectRoot);
             emitGate((0, hook_program_js_1.decideFileGate)(program, event, ctx, projectRoot), program.on, (0, hook_program_js_1.hookMode)(program), file);
             return;
         }
         case "bash-gate": {
-            const ctx = await gatherHookContext(program);
+            const ctx = await gatherHookContext(program, file);
             // The same `projectRoot` the file gates get: without it every
             // repo-relative prefix in a DENYLIST matcher (`touches`/`writesTo`) is
             // matched by over-blocking alone, and with it an absolute token is placed
@@ -5534,12 +5632,12 @@ async function runHookProgramCommand(file) {
             return;
         }
         case "prompt-gate": {
-            const ctx = await gatherHookContext(program);
+            const ctx = await gatherHookContext(program, file);
             emitGate((0, hook_program_js_1.decidePromptGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
             return;
         }
         case "stop-gate": {
-            const ctx = await gatherHookContext(program);
+            const ctx = await gatherHookContext(program, file);
             emitGate((0, hook_program_js_1.decideStopGate)(program, event, ctx), program.on, (0, hook_program_js_1.hookMode)(program), file);
             return;
         }

package/dist/core/bash-effects.d.ts

@@ -112,6 +112,26 @@ export interface NormalizedLeaf {
      * {@link LeafRedirect}. Empty for a command with no redirection.
      */
     readonly redirects: readonly LeafRedirect[];
+    /**
+     * The directory a chdir WRAPPER moved this leaf into before exec'ing it —
+     * `env -C dir`, `env --chdir=dir`, `sudo -D dir` — or `null` when there was
+     * none. Nested wrappers accumulate (`sudo -D a env -C b cmd` → `a/b`).
+     *
+     * The parser already READ this token in order to skip past it, then threw the
+     * value away — so every relative operand of the wrapped command resolved
+     * against the wrong directory for every consumer. Same shape as the
+     * redirection targets the leaf used to drop: the parser knew, the leaf did
+     * not carry it. `git -C` is deliberately NOT here — `git` is not a wrapper
+     * (it does not exec the rest of its argv as a command).
+     *
+     * ⚠️ ONE LEAF'S OWN WRAPPER, NOT A CWD MODEL. A directory changed by a
+     * PRECEDING statement (`cd x && …`, `pushd`, a subshell) is not reported:
+     * connectors do not survive leaf extraction, and `cd x; cmd` writes into the
+     * OLD directory when the `cd` fails — that is a model with failure semantics,
+     * not a field. A dynamic value (`env -C "$DIR" …`) is not resolvable and the
+     * whole leaf is already unnormalizable in that case.
+     */
+    readonly chdir: string | null;
 }
 /**
  * Extract every simple command as a {@link NormalizedLeaf} — the operation-level

package/dist/core/bash-effects.js

@@ -617,6 +617,38 @@ const WRAPPER_VALUE_OPTS = {
     ]),
     nohup: new Set(),
 };
+/**
+ * Per-wrapper options whose value is a DIRECTORY the wrapper chdirs into before
+ * exec'ing the command. A subset of {@link WRAPPER_VALUE_OPTS}, and keyed by head
+ * for a reason: `-C` is `--chdir` for `env` but `--close-from` (a file
+ * descriptor) for `sudo`, whose chdir is `-D`. One shared set would read a
+ * number as a directory.
+ */
+const WRAPPER_CHDIR_OPTS = {
+    env: new Set(["-C", "--chdir"]),
+    sudo: new Set(["-D", "--chdir"]),
+};
+/**
+ * The directory carried by an option WORD, when that word is one of this
+ * wrapper's chdir options — covering both spellings, since `--chdir=dir` is a
+ * single token that never reaches the separate-value table.
+ */
+function chdirValue(word, next, chdirOpts) {
+    if (chdirOpts.has(word))
+        return next; // `-C dir`, `--chdir dir`
+    const eq = word.indexOf("=");
+    return eq > 0 && chdirOpts.has(word.slice(0, eq))
+        ? word.slice(eq + 1) // `--chdir=dir`
+        : undefined;
+}
+/** Layer a wrapper's chdir onto the one an outer wrapper already applied. */
+function nestChdir(outer, inner) {
+    if (inner === undefined || inner === "")
+        return outer;
+    if (outer === null || inner.startsWith("/") || /^[A-Za-z]:\//.test(inner))
+        return inner;
+    return `${outer.replace(/\/+$/, "")}/${inner}`;
+}
 /** Count of leading NON-option positionals a wrapper consumes before the command (timeout DURATION). */
 const WRAPPER_SKIP_POSITIONALS = {
     timeout: 1,
@@ -640,12 +672,14 @@ function splitAssignmentWord(word) {
  */
 function stripWrappers(argv) {
     const envAssigns = new Map();
+    let chdir = null;
     let cur = argv;
     for (let guard = 0; guard < 8; guard++) {
         const head = cur[0];
         if (head === undefined || !WRAPPER_HEADS.has(head))
             break;
         const valueOpts = WRAPPER_VALUE_OPTS[head] ?? new Set();
+        const chdirOpts = WRAPPER_CHDIR_OPTS[head] ?? new Set();
         let positionalsToSkip = WRAPPER_SKIP_POSITIONALS[head] ?? 0;
         let i = 1; // start after the wrapper head
         let ended = false;
@@ -659,6 +693,11 @@ function stripWrappers(argv) {
                 break;
             }
             if (a.length > 1 && a.startsWith("-")) {
+                // The chdir value is CAPTURED before it is skipped. It was always read
+                // here — reading it is how the loop knows to skip past it — and then
+                // discarded, so every relative operand of the wrapped command resolved
+                // against the wrong directory downstream.
+                chdir = nestChdir(chdir, chdirValue(a, cur[i + 1], chdirOpts));
                 if (valueOpts.has(a))
                     i++; // skip this option's separate value too
                 continue;
@@ -682,7 +721,7 @@ function stripWrappers(argv) {
             break; // no progress → stop
         cur = next;
     }
-    return { argv: cur, envAssigns };
+    return { argv: cur, envAssigns, chdir };
 }
 /**
  * Extract every simple command as a {@link NormalizedLeaf} — the operation-level
@@ -1056,6 +1095,7 @@ function normalizeCallExpr(node, redirs) {
         assigns,
         hasAssign: (...names) => names.some((n) => assigns.has(n)),
         redirects: normalizeRedirects(redirs),
+        chdir: stripped.chdir,
     };
 }
 //# sourceMappingURL=bash-effects.js.map

package/dist/core/hook-program.d.ts

@@ -34,6 +34,47 @@ import { type SHA256Hash } from "./hash.js";
 import type { HarnessDialect } from "./dialect.js";
 import type { HookProtocol } from "./hook-protocol.js";
 import { type ProviderName, type NeedSpec, type HookCtx } from "./hook-providers.js";
+import { type StateFact, type StateWrite } from "./hook-state.js";
+/**
+ * The erased runtime shape of a gathered context. Author-facing types keep the
+ * precise `HookCtx<N>`; the decode functions re-narrow and cast.
+ */
+type RawCtx = Record<string, string | boolean | StateFact>;
+/**
+ * Does `name` match a hook's declared tool list, under the SAME semantics as the
+ * matcher the compiler emits for it?
+ *
+ * 🔴 IT DID NOT, AND THE DISAGREEMENT WAS SILENT. `hookRouting` joins a react's
+ * tools with `|` and emits that as the harness matcher, and a Claude Code matcher
+ * is a REGEX — `Edit|Write|MultiEdit` only works because it is one. The runtime
+ * meanwhile compared with `Array.includes`, i.e. exact string equality. So a hook
+ * declaring a tool FAMILY compiled fine, was wired up fine, was routed to by the
+ * harness fine, and was then dropped by vigiles' own filter without a word.
+ *
+ * MEASURED 2026-08-12 against the real runtime, before the fix:
+ *
+ *   $ echo '{"tool_name":"mcp__4f54037d-0499__list_events",…}' \
+ *       | vigiles hook-runtime run-program mcp-family.hook.mjs
+ *   exit=0                       # silence — react() never ran
+ *   $ echo '{"tool_name":"mcp__.*",…}' | …
+ *   FIRED on mcp__.*             # fires only for a tool LITERALLY named "mcp__.*"
+ *
+ * That is the false-confidence class this whole subsystem exists to eliminate,
+ * living inside the subsystem. The live evidence that the harness really does
+ * route these: the knowledge base has shipped `"matcher": "mcp__.*"` in
+ * `.claude/settings.json` for months and its stamp file was last written the
+ * morning this was measured. The MCP server's id changes per session, so an exact
+ * list cannot be written down — a family matcher is the only correct spelling.
+ *
+ * Anchored `^(…)$` so a pattern cannot match a longer tool name by accident, and
+ * identical to `includes` for ordinary names, which contain no metacharacters.
+ * An unparseable pattern is rejected at COMPILE ({@link invalidToolPatterns}), so
+ * the fallback here is unreachable in a compiled hook and exists only so that a
+ * hand-constructed one degrades to exact matching rather than throwing mid-event.
+ */
+export declare function matchesTool(tools: readonly string[], name: string): boolean;
+/** Tool patterns that are not valid regexes — rejected at compile, see {@link matchesTool}. */
+export declare function invalidToolPatterns(tools: readonly string[]): string[];
 export type Decision = {
     readonly kind: "allow";
 } | {
@@ -128,8 +169,33 @@ export interface CommandView {
      *
      * Deletion is a different question and is deliberately NOT reported here —
      * pair with `runs("rm")` if a gate cares about removal too.
+     *
+     * Exactly `writeTargets(prefixes).length > 0`, and implemented as that — reach
+     * for {@link writeTargets} when the gate needs to know WHICH file.
      */
     writesTo(prefixes: readonly string[]): boolean;
+    /**
+     * The write targets of this command that fall under one of the prefixes — the
+     * "WHICH file is written" counterpart to {@link writesTo}. Same two AST-backed
+     * sources (redirection targets + file-writing programs' argv positions), same
+     * denylist bias (an undecidable placement is INCLUDED).
+     *
+     * Spelling is as-written after normalization — quote-unwrapped,
+     * `$HOME`-canonicalized, and resolved against the leaf's own chdir wrapper
+     * (`env -C dir sed -i x` reports `dir/x`) — in order of appearance, exact
+     * duplicates collapsed. Filter by basename/suffix; never re-match the prefixes
+     * by hand, because hand-rolled prefix matching is the exact source of the
+     * trailing-slash, absolute-path and root-blindness defects this vocabulary
+     * exists to remove.
+     *
+     * An empty array ⇔ `writesTo(prefixes) === false`, so the natural
+     * `writeTargets(P).some(pred)` needs no emptiness check to behave correctly.
+     *
+     * `prefixes` is REQUIRED and there is no unfiltered overload: the raw list
+     * does not cross the API boundary, because a consumer holding it has to
+     * re-implement the matching that {@link prefixVerdict} exists to own.
+     */
+    writeTargets(prefixes: readonly string[]): readonly string[];
     /**
      * True iff the command pipes into a BARE shell interpreter (`curl … | sh`,
      * `… | bash -s`) — the remote-code-execution shape. High-signal: a shell leaf
@@ -214,7 +280,7 @@ export declare function decideProgram<N extends readonly NeedSpec[]>(program: Ho
         command?: unknown;
     };
     cwd?: unknown;
-}, ctx?: Record<string, string | boolean>, root?: string | undefined): Decision;
+}, ctx?: RawCtx, root?: string | undefined): Decision;
 /** Map a Decision to the CC hook exit code — the protocol the author never writes. */
 export declare function decisionExitCode(d: Decision): number;
 /**
@@ -277,7 +343,7 @@ export interface CompileHookOptions {
  * (they never trust this type). Author-facing types keep the precise `N`.
  */
 type ErasedNeeds = readonly any[];
-export type AnyHook = HookProgram<ErasedNeeds> | FileGateHook<ErasedNeeds> | PromptGateHook<ErasedNeeds> | StopGateHook<ErasedNeeds> | InjectHook | ReactHook;
+export type AnyHook = HookProgram<ErasedNeeds> | FileGateHook<ErasedNeeds> | PromptGateHook<ErasedNeeds> | StopGateHook<ErasedNeeds> | InjectHook<ErasedNeeds> | ReactHook<ErasedNeeds>;
 /**
  * The runtime dispatch shapes. A bare {@link HookProgram} (no `role`) is a Bash
  * command gate; the role-keyed hooks carry their own shape. The runtime uses this
@@ -456,7 +522,7 @@ export declare function decideFileGate<N extends readonly NeedSpec[]>(hook: File
         file_path?: unknown;
     };
     cwd?: unknown;
-}, ctx?: Record<string, string | boolean>, root?: string | undefined): Decision;
+}, ctx?: RawCtx, root?: string | undefined): Decision;
 /** The event a UserPromptSubmit gate decides over — it sees the prompt TEXT. */
 export interface PromptEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
     readonly event: string;
@@ -480,7 +546,7 @@ export declare function definePromptGate<const N extends readonly NeedSpec[] = r
 /** Run a prompt gate against a raw UserPromptSubmit event (reads `prompt`). */
 export declare function decidePromptGate<N extends readonly NeedSpec[]>(hook: PromptGateHook<N>, raw: {
     prompt?: unknown;
-}, ctx?: Record<string, string | boolean>): Decision;
+}, ctx?: RawCtx): Decision;
 /**
  * The event a Stop gate decides over. `deny` BLOCKS the agent from ending its
  * turn (the reason is surfaced to the agent — e.g. "tests are red, keep going").
@@ -511,38 +577,65 @@ export declare function defineStopGate<const N extends readonly NeedSpec[] = rea
 /** Run a Stop gate against a raw Stop/SubagentStop event (reads `stop_hook_active`). */
 export declare function decideStopGate<N extends readonly NeedSpec[]>(hook: StopGateHook<N>, raw: {
     stop_hook_active?: unknown;
-}, ctx?: Record<string, string | boolean>): Decision;
+}, ctx?: RawCtx): Decision;
 /** The output of an inject hook — text to add to context. NO allow/deny exists here. */
 export interface Injection {
     readonly kind: "inject";
     readonly context: string;
+    /** Facts to record — a DECLARATION; the trusted runtime performs the write. */
+    readonly records: readonly StateWrite[];
 }
-export declare const inject: (context: string) => Injection;
-/** The event an inject hook produces from (no tool — SessionStart/UserPromptSubmit). */
-export interface SessionEvent {
+/**
+ * Context to add, plus any facts that just became true:
+ * `inject(text, record("calendar.nagged"))`.
+ *
+ * The writes are trailing arguments on every output builder, so there is one rule
+ * to learn rather than a per-role spelling — and a hook that records nothing is
+ * written exactly as it was before.
+ */
+export declare const inject: (context: string, ...records: readonly StateWrite[]) => Injection;
+/**
+ * The event an inject hook produces from (no tool — SessionStart/UserPromptSubmit).
+ * Generic over its declared `needs`, exactly like the gate events.
+ */
+export interface SessionEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
     readonly event: string;
     readonly source: string;
+    /** Host-gathered, DECLARED facts — built-ins, inline providers, and `state()` reads. */
+    readonly ctx: HookCtx<N>;
 }
-export interface InjectHook {
+export interface InjectHook<N extends readonly NeedSpec[] = readonly ProviderName[]> {
     readonly role: "inject";
     readonly on: string;
+    /**
+     * Declared context providers the trusted runtime gathers into `e.ctx`.
+     *
+     * Injects and reacts could not declare `needs` at all until state landed, for
+     * no reason anyone had recorded — and a fact a hook cannot read is not a
+     * feature. `needs` is now uniform across every role.
+     */
+    readonly needs?: N;
     /** Produces context to add. Its return type (Injection) has no `deny` — by design. */
-    readonly produce: (e: SessionEvent) => Injection;
+    readonly produce: (e: SessionEvent<N>) => Injection;
 }
-export declare const defineInject: (p: Omit<InjectHook, "role">) => InjectHook;
+export declare function defineInject<const N extends readonly NeedSpec[] = readonly []>(p: Omit<InjectHook<N>, "role">): InjectHook<N>;
 /**
  * Run an inject hook → the CC JSON the author never hand-writes. The compiler
  * targets `additionalContext` (the RIGHT field for this event), so the
  * wrong-JSON-field pain can't occur.
  */
-export declare function runInject(hook: InjectHook, raw: {
+export declare function runInject<N extends readonly NeedSpec[]>(hook: InjectHook<N>, raw: {
     source?: string;
-}): {
+}, ctx?: RawCtx): {
     hookSpecificOutput: {
         hookEventName: string;
         additionalContext: string;
     };
 };
+/** The full {@link Injection} — the runtime needs its `records`, which the CC JSON drops. */
+export declare function injectionOf<N extends readonly NeedSpec[]>(hook: InjectHook<N>, raw: {
+    source?: string;
+}, ctx?: RawCtx): Injection;
 /**
  * A view of a tool's RESPONSE (PostToolUse) — the matching primitive a react hook
  * reasons over (e.g. capture/notify only when a command FAILED). The author never
@@ -561,54 +654,88 @@ export interface ResponseView {
 }
 export declare function responseView(raw: unknown): ResponseView;
 /** The event a react hook reacts over — the tool, the file path, AND its response. */
-export interface ReactEvent {
+export interface ReactEvent<N extends readonly NeedSpec[] = readonly ProviderName[]> {
     readonly event: string;
     readonly tool: string;
     readonly path: PathView;
     /** The tool's response (PostToolUse) — react only on an error, capture output, … */
     readonly response: ResponseView;
+    /** Host-gathered, DECLARED facts — built-ins, inline providers, and `state()` reads. */
+    readonly ctx: HookCtx<N>;
 }
 export interface RunReaction {
     readonly kind: "run";
     readonly command: string;
     readonly effect: BashEffect;
+    readonly records: readonly StateWrite[];
 }
 export type Reaction = RunReaction | {
     readonly kind: "notice";
     readonly message: string;
+    readonly records: readonly StateWrite[];
 } | {
     readonly kind: "none";
+    readonly records: readonly StateWrite[];
 };
-/** Run a command in reaction — its effect is classified AT CONSTRUCTION (audit/diff-able). */
-export declare const run: (command: string) => RunReaction;
-/** Surface a non-blocking note (no execution). */
-export declare const notice: (message: string) => Reaction;
-/** Do nothing. */
-export declare const nothing: () => Reaction;
-export interface ReactHook {
+/**
+ * Run a command in reaction — its effect is classified AT CONSTRUCTION
+ * (audit/diff-able). Trailing arguments record facts.
+ *
+ * ⚠️ `run()` is for invoking a real TOOL. Using it to write a stamp
+ * (`run("date +%s > .claude/.stamp")`) was the only way to remember anything
+ * before `record()` existed; it is now the wrong tool — it spends a subprocess
+ * and a shell on a variable assignment, and it classifies as side-effecting.
+ */
+export declare const run: (command: string, ...records: readonly StateWrite[]) => RunReaction;
+/** Surface a non-blocking note (no execution). Trailing arguments record facts. */
+export declare const notice: (message: string, ...records: readonly StateWrite[]) => Reaction;
+/**
+ * Take no action. Trailing arguments still record facts — `nothing(record("x"))`
+ * is the shape of a hook whose entire job is to WITNESS that something happened
+ * (an MCP call, a deploy) so a different hook can read it later.
+ */
+export declare const nothing: (...records: readonly StateWrite[]) => Reaction;
+export interface ReactHook<N extends readonly NeedSpec[] = readonly ProviderName[]> {
     readonly role: "react";
     readonly on: string;
-    readonly match: {
+    /**
+     * Which tools to react to. OMIT IT for an event that carries no tool at all
+     * (`Stop`, `SubagentStop`, `SessionEnd`), exactly as inject and the prompt/stop
+     * gates already do — `hookRouting` then emits no matcher.
+     *
+     * 🔴 IT USED TO BE REQUIRED, WHICH MADE EVERY TOOL-LESS REACT DEAD. `runReact`
+     * gates on `tool_name`; a `Stop` event carries none, so the name defaulted to
+     * `""`, matched nothing, and the hook returned `nothing()` forever. MEASURED
+     * 2026-08-12 against the real runtime: a `Stop` react printed nothing and
+     * exited 0 — indistinguishable from a hook that decided to stay quiet, which
+     * is the whole reason advisory hooks die unnoticed. Three of the seven hooks
+     * this feature was built for are `Stop` nudges.
+     */
+    readonly match?: {
         readonly tools: readonly string[];
     };
+    /** Declared context providers the trusted runtime gathers into `e.ctx`. */
+    readonly needs?: N;
     /** Reacts to a tool that already ran. Returns a Reaction — NO `deny` exists here. */
-    readonly react: (e: ReactEvent) => Reaction;
+    readonly react: (e: ReactEvent<N>) => Reaction;
 }
-export declare const defineReact: (p: Omit<ReactHook, "role">) => ReactHook;
+export declare function defineReact<const N extends readonly NeedSpec[] = readonly []>(p: Omit<ReactHook<N>, "role">): ReactHook<N>;
 /**
  * Run a react hook against a raw PostToolUse event → the (classified) Reaction.
  *
  * `root` behaves exactly as in {@link decideFileGate}: the event's own `cwd` by
- * default, the CLI's {@link projectRootOf} when the runtime supplies one.
+ * default, the CLI's {@link projectRootOf} when the runtime supplies one. It
+ * trails `ctx` so the argument order matches {@link decideProgram} and
+ * {@link decideFileGate} — every decode function reads `(hook, raw, ctx, root)`.
  */
-export declare function runReact(hook: ReactHook, raw: {
+export declare function runReact<N extends readonly NeedSpec[]>(hook: ReactHook<N>, raw: {
     tool_name?: string;
     tool_input?: {
         file_path?: unknown;
     };
     tool_response?: unknown;
     cwd?: unknown;
-}, root?: string | undefined): Reaction;
+}, ctx?: RawCtx, root?: string | undefined): Reaction;
 /** The raw event fields the decode functions read (the union across roles). */
 export interface RawHookEvent {
     readonly tool_name?: string;
@@ -638,10 +765,22 @@ export type HookProgramOutcome = {
 } | {
     readonly kind: "injection";
     readonly context: string;
+    readonly records: readonly StateWrite[];
 } | {
     readonly kind: "reaction";
     readonly reaction: Reaction;
 };
+/**
+ * The state writes an outcome declares, filtered to the ones the runtime may
+ * actually perform. A gate's `Decision` carries none — deliberately: a gate is
+ * the role that must be trustworthy and runs on every tool call, so it READS
+ * state (via `needs`) and never writes it. Adding a write there later is easy;
+ * removing one would not be.
+ */
+export declare function outcomeWrites(outcome: HookProgramOutcome): {
+    readonly ok: readonly StateWrite[];
+    readonly refused: readonly string[];
+};
 /** Record where a hook program was loaded from. Called by `loadHook` ONLY. */
 export declare function rememberHookSource(hook: AnyHook, file: string): void;
 /** The file a hook was loaded from, or `undefined` for one built in-process. */
@@ -652,7 +791,7 @@ export declare function hookSource(hook: AnyHook): string | undefined;
  * (effect-classified) `Reaction`. Pure — no subprocess, no model. The ergonomic
  * base for testing a compiled hook (see `assertHookDenies` / `assertHookAllows`).
  */
-export declare function runHookProgram(hook: AnyHook, event: RawHookEvent, ctx?: Record<string, string | boolean>, root?: string | undefined): HookProgramOutcome;
+export declare function runHookProgram(hook: AnyHook, event: RawHookEvent, ctx?: RawCtx, root?: string | undefined): HookProgramOutcome;
 /**
  * The repository a wedged hook belongs to, as the runtime sees it. Supplied by
  * the caller because core takes no `node:path` and reads no disk — and because