Local-first 🧠memory for Hermes Agent that lives in your Obsidian vault and remembers project context. Nightly 😴 dream passes turn repeat corrections into confirmed preferences with measurable confidence. Adapters ship for Claude Code, Codex, and OpenClaw, with an MCP server for anything else.
TypeScript
#!/usr/bin/env -S bun
/**
* Stop hook: answer-time quote verification (answer-trust wave, Lane A).
*
* At turn end this step reads the LAST assistant messages of the turn,
* finds their quoted spans with the distill lane's own
* `findQuoteSpans`, and checks each span against the evidence the turn
* actually had:
*
* - the note the span cites - a wikilink target or a vault-relative
* path in the message text, resolved against the vault; and
* - otherwise the notes the injection ledger says entered context this
* session, across the four phase keys (recall keys, the active
* digest's emitted paths plus its queued re-delivery parts, and the
* note paths the sub-agent carrier recorded with its deliveries).
*
* Each span gets one verdict from
* `src/core/brain/answer-quotes/check.ts` - `verified`, `not-in-note`,
* `source-truncated`, `note-unavailable` or `not-text` - and the
* unverified ones are listed in exactly ONE
* `hookSpecificOutput.additionalContext` annotation (the
* `hooks/stop-log-guardrail.ts` precedent). The hook NEVER blocks and
* NEVER edits the transcript: a verdict is reported, not enforced.
*
* Phases. A phase runs only when BOTH hold: the phase's injection is
* enabled (recall requires `recall_inject_enabled`; active and subagent
* require a live injection ledger for the session) and its
* `quote_check.<phase>` resolver returns more than `off`.
* `shadow` annotates only; `enforce` additionally appends exactly one
* Brain-log event per turn with the unverified spans, so findings survive
* the session - and never blocks.
*
* Channel. The annotation rides `hookSpecificOutput.additionalContext`
* on the Stop event, which Claude Code renders into the turn. Codex and
* grok accept the registration but render no Stop annotation - and grok
* ships no `transcript_path` at all - so the check is silently inert on
* them: fail-open silence, kept deliberately, with the `enforce`
* Brain-log trail as the one finding surface that survives the session.
*
* Reply presence (t_f8510c55). Wherever a transcript exists - annotation
* rendering or not - every checked turn also appends exactly one
* `reply_presence` continuity record: per injected note, whether a
* quoted span verified against it, its strongest miss verdict, `absent`
* when no span was ever measured against it, or `note-unavailable` when
* the budget cut the walk before the note could be measured. A span
* that verified is measured against the note that carries it alone, so
* the per-note verdicts hold whichever way the candidates sort. The
* record is keyed by session id and joined to the session's context
* receipts on read; identifiers and verdicts only, never answer text.
* The presence record rides the same per-phase modes: every phase `off`
* writes nothing.
*
* Bounded, fail-open. The step reads at most
* {@link ANSWER_QUOTE_TAIL_BYTES} of the transcript, the last
* {@link ANSWER_QUOTE_MAX_MESSAGES} assistant messages of the turn,
* {@link ANSWER_QUOTE_MAX_CHARS} characters of each, and gives up by
* checking nothing further once {@link ANSWER_QUOTE_BUDGET_MS} have
* passed - unchecked spans are dropped rather than run long. Every error
* path exits 0 with exactly one stderr audit line, producing nothing.
* Fires at most once per turn: when the runtime reports
* `stop_hook_active === true` (this turn was already continued by a Stop
* hook) the hook exits 0 silently.
*/
import {
closeSync,
existsSync,
fstatSync,
openSync,
readFileSync,
readSync,
statSync,
} from "node:fs";
import { createHash } from "node:crypto";
import {
resolveAnswerQuoteCheckActive,
resolveAnswerQuoteCheckRecall,
resolveAnswerQuoteCheckSubagent,
resolveAgentName,
resolveRecallInjectEnabled,
type AnswerQuoteCheckMode,
type AnswerQuoteCheckPhase,
ANSWER_QUOTE_CHECK_PHASES,
} from "../src/core/config.ts";
import {
ANSWER_QUOTE_VERDICT,
checkAnswerQuotes,
mergeAnswerQuoteVerdicts,
previewAnswerQuoteSpan,
type AnswerQuoteEvidence,
type AnswerQuoteVerdict,
} from "../src/core/brain/answer-quotes/check.ts";
import { findQuoteSpans } from "../src/core/brain/distill/quote-spans.ts";
import { brainConfigPath } from "../src/core/brain/paths.ts";
import {
neutralizeUntrustedText,
untrustedFramingHeader,
} from "../src/core/brain/untrusted-source.ts";
import { appendLogEvent } from "../src/core/brain/log.ts";
import { BRAIN_LOG_EVENT_KIND } from "../src/core/brain/types.ts";
import { isoSecond } from "../src/core/brain/time.ts";
import { appendContinuityRecord } from "../src/core/brain/continuity/store.ts";
import { CONTINUITY_SESSION_ID_KEY } from "../src/core/brain/continuity/types.ts";
import { ensureInsideVault } from "../src/core/path-safety.ts";
import { asHookPayload, readHookInput } from "./lib/stdin.ts";
import {
isRealSessionId,
LEDGER_KEY_REGROUND,
readActiveEmittedPaths,
readRecallInjected,
readSubagentDeliveredPaths,
} from "./lib/injection-ledger.ts";
import { readHookStamp } from "./lib/session-state.ts";
import { resolveHookTarget } from "./lib/hook-vault.ts";
/**
* The last assistant messages of the turn the check reads. Everything
* older is another turn's answer.
*/
export const ANSWER_QUOTE_MAX_MESSAGES = 6;
/** Per-message character budget: the prefix of a message that is checked. */
export const ANSWER_QUOTE_MAX_CHARS = 4000;
/** The shipped wall-clock budget for the whole check. */
const ANSWER_QUOTE_DEFAULT_BUDGET_MS = 1500;
/**
* The wall-clock budget, resolved ONCE at module load: a spawned hook
* process honors an `ANSWER_QUOTE_BUDGET_MS` environment override - a
* test seam for the budget-expiry arms, read a single time so a child's
* whole run sees one budget; anything absent, blank or unparsable keeps
* the shipped default.
*/
function resolveBudget(): number {
const raw = process.env["ANSWER_QUOTE_BUDGET_MS"]?.trim();
if (raw === undefined || raw.length === 0) return ANSWER_QUOTE_DEFAULT_BUDGET_MS;
const parsed = Number(raw);
return Number.isFinite(parsed) ? parsed : ANSWER_QUOTE_DEFAULT_BUDGET_MS;
}
/** Wall-clock budget for the whole check; past it, unchecked spans are dropped. */
export const ANSWER_QUOTE_BUDGET_MS: number = resolveBudget();
/**
* Ceiling on findings rendered in one annotation - and in one enforce
* event: past it the tail of the list collapses into one "and N more"
* line, so a pathological answer annotates its first spans instead of
* flooding the context channel.
*/
export const ANSWER_QUOTE_MAX_FINDINGS = 20;
/**
* Byte window of the bounded transcript tail read. Small enough that a
* huge transcript cannot slow the Stop path, large enough to hold the
* current turn's answers; the reader drops the one line the window may
* have cut in half.
*/
export const ANSWER_QUOTE_TAIL_BYTES = 262_144;
/**
* Ceiling on how much of one cited note the check reads, on the 1 MiB
* scale of the ingest archive ceiling. Past it only the head of the file
* is read and the evidence is named truncated - a miss against it is
* `source-truncated`, never `not-in-note` - and a pointer that names a
* line range is refused as `unavailable` rather than served a slice of
* the prefix as if it were the named lines.
*/
export const ANSWER_QUOTE_NOTE_MAX_BYTES = 1_048_576;
/** Stderr audit prefix: every error arm prints exactly one line with it. */
const AUDIT_PREFIX = "answer-quote-check:";
/** One quoted span to check: its text and where it sits in its message. */
interface QuotedSpan {
readonly message: number;
readonly inner: string;
readonly open: number;
readonly close: number;
}
/** One citation mark found in a message: a note reference and its offset. */
interface CitationMark {
readonly at: number;
/** Vault-relative note path, `.md`-complete. */
readonly path: string;
/** 1-based inclusive line range, when the pointer names one. */
readonly startLine?: number;
readonly endLine?: number;
}
/**
* A vault-relative `.md` path pointer, optionally naming a line range the
* way every recall pointer renders it (`Brain/notes/x.md:L3-L9`). Requires
* at least one directory separator, so a bare word before `.md` is prose,
* not a pointer.
*
* The repeated class MUST exclude `/`. A class that can match the
* separator itself segments a run of N slashes 2^(N-1) ways, and the scan
* a hook feeds it routinely fails (a base64 blob in an answer carries
* hundreds of slashes and no `.md`), so the engine walks every
* segmentation and the Stop hook stalls past its 10 s timeout - the
* CodeQL high on this file. With `/` excluded the scan is linear in the
* text; the one reading that changes is `a//b/c.md`, now `b/c.md`.
*/
const PATH_POINTER_RE = /(?:[^\s:|[\]()#/]+\/)+[^\s:|[\]()#/]*\.md(?::L(\d+)-L(\d+))?/g;
/**
* A `.md` path token, for scanning ledger member strings that are prose.
* Excludes `/` for the same reason as {@link PATH_POINTER_RE}.
*/
const PATH_TOKEN_RE = /(?:[^\s:|[\]()#/]+\/)+[^\s:|[\]()#/]*\.md/g;
// ----- transcript tail -----------------------------------------------------
/**
* Fill `length` bytes of `fd` from `start`, looping on `readSync` until
* the window is filled or EOF: a single positional read may return
* short, and a short read would silently shrink the window.
*/
function readWindow(fd: number, start: number, length: number): Buffer {
const buffer = Buffer.alloc(length);
let filled = 0;
while (filled < buffer.length) {
const moved = readSync(fd, buffer, filled, buffer.length - filled, start + filled);
if (moved <= 0) break;
filled += moved;
}
return filled === buffer.length ? buffer : buffer.subarray(0, filled);
}
/**
* The last {@link ANSWER_QUOTE_TAIL_BYTES} of the transcript as text. One
* bounded positional read; the caller drops the line the window may have
* cut in half.
*/
function readTail(path: string): { readonly text: string; readonly cutStart: boolean } {
const fd = openSync(path, "r");
try {
const stat = fstatSync(fd);
// POSIX refuses to open a directory; Windows opens it and reports size
// 0, which would read as an empty transcript - silence where every
// platform must see one audit line. Name the failure identically
// everywhere instead: only a regular file is a transcript.
if (!stat.isFile()) throw new Error(`transcript is not a regular file: ${path}`);
const start = Math.max(0, stat.size - ANSWER_QUOTE_TAIL_BYTES);
return { text: readWindow(fd, start, stat.size - start).toString("utf8"), cutStart: start > 0 };
} finally {
closeSync(fd);
}
}
/** First string `value`'s text blocks join to, or `""`. */
function textBlocks(content: unknown): string {
if (typeof content === "string") return content;
if (!Array.isArray(content)) return "";
return content
.filter(
(block): block is { readonly text: string } =>
typeof block === "object" &&
block !== null &&
typeof (block as { text?: unknown }).text === "string",
)
.map((block) => block.text)
.join("\n");
}
/** A real user turn boundary in either transcript shape (not a tool result). */
function isUserBoundary(record: Record<string, unknown>): boolean {
const message = record["message"] as Record<string, unknown> | undefined;
if (
record["type"] === "user" &&
message !== null &&
typeof message === "object" &&
message["role"] === "user"
) {
const content = message["content"];
// Tool results ride user-role records too; they are not a turn boundary.
const toolResultsOnly =
Array.isArray(content) &&
content.length > 0 &&
content.every(
(block) => typeof block === "object" && block !== null && block["type"] === "tool_result",
);
return !toolResultsOnly;
}
const payload = record["payload"] as Record<string, unknown> | undefined;
if (record["type"] === "response_item" && payload !== null && typeof payload === "object") {
if (payload["type"] !== "message" || payload["role"] !== "user") return false;
const text = textBlocks(payload["content"]);
// Codex prepends synthetic envelopes; they are not a user prompt.
return !text.startsWith("<environment_context>") && !text.startsWith("<user_instructions>");
}
return false;
}
/** Assistant message text of one record, or `""` when the record has none. */
function assistantText(record: Record<string, unknown>): string {
const message = record["message"] as Record<string, unknown> | undefined;
if (record["type"] === "assistant" && message !== null && typeof message === "object") {
return textBlocks(message["content"]);
}
const payload = record["payload"] as Record<string, unknown> | undefined;
if (
record["type"] === "response_item" &&
payload !== null &&
typeof payload === "object" &&
payload["type"] === "message" &&
payload["role"] === "assistant"
) {
return textBlocks(payload["content"]);
}
return "";
}
/**
* The last assistant messages of the turn, in answer order: the records
* after the newest real user message inside the tail window, capped to
* {@link ANSWER_QUOTE_MAX_MESSAGES} messages and
* {@link ANSWER_QUOTE_MAX_CHARS} characters each. A window that holds no
* user boundary contributes its newest assistant messages - the tail of
* the current turn - which is what the check wants.
*/
function lastAssistantMessages(transcriptPath: string): ReadonlyArray<string> {
const { text, cutStart } = readTail(transcriptPath);
const lines = text.split(/\r?\n/).filter((line) => line.length > 0);
// The first line of a mid-file window is cut in half by the window, not
// written broken by the host.
const whole = cutStart ? lines.slice(1) : lines;
const records: ReadonlyArray<Record<string, unknown>> = whole.flatMap((line) => {
try {
const parsed = JSON.parse(line) as unknown;
return parsed !== null && typeof parsed === "object"
? [parsed as Record<string, unknown>]
: [];
} catch {
return [];
}
});
const messages: string[] = [];
for (let i = records.length - 1; i >= 0 && messages.length < ANSWER_QUOTE_MAX_MESSAGES; i--) {
const record = records[i]!;
if (isUserBoundary(record)) break;
const body = assistantText(record);
if (body.length === 0) continue;
messages.push(
body.length > ANSWER_QUOTE_MAX_CHARS ? body.slice(0, ANSWER_QUOTE_MAX_CHARS) : body,
);
}
return messages.toReversed();
}
// ----- citations and evidence ----------------------------------------------
/** Wikilink targets of `text`, as citation marks at their offsets. */
function wikilinkMarks(text: string): CitationMark[] {
const marks: CitationMark[] = [];
for (const match of text.matchAll(/\[\[([^\]|#]+)(?:[#|][^\]]*)?\]\]/g)) {
const target = match[1]?.trim();
if (target === undefined || target.length === 0) continue;
marks.push({
at: match.index!,
path: target.endsWith(".md") ? target : `${target}.md`,
});
}
return marks;
}
/** Vault-relative path pointers of `text`, with any line range they name. */
function pathPointerMarks(text: string): CitationMark[] {
const marks: CitationMark[] = [];
for (const match of text.matchAll(PATH_POINTER_RE)) {
const startLine = match[1] === undefined ? undefined : Number(match[1]);
const endLine = match[2] === undefined ? undefined : Number(match[2]);
marks.push({
at: match.index!,
path:
startLine === undefined || endLine === undefined
? match[0]
: match[0].slice(0, match[0].lastIndexOf(":L")),
...(startLine !== undefined && endLine !== undefined ? { startLine, endLine } : {}),
});
}
return marks;
}
/** The citation marks of one message: offset-sorted, duplicate-free. */
function citationMarks(text: string): ReadonlyArray<CitationMark> {
const byKey = new Map<string, CitationMark>();
for (const mark of [...wikilinkMarks(text), ...pathPointerMarks(text)]) {
const key = `${mark.path}\0${mark.startLine ?? ""}-${mark.endLine ?? ""}`;
const existing = byKey.get(key);
if (existing === undefined || mark.at < existing.at) byKey.set(key, mark);
}
return [...byKey.values()].toSorted((a, b) => a.at - b.at);
}
/**
* Vault-absolute path of a cited note, or `null` when the reference
* escapes the vault. Exists-checking is the caller's concern.
*/
function resolveNotePath(vault: string, relativePath: string): string | null {
try {
return ensureInsideVault(`${vault}/${relativePath}`, vault);
} catch {
return null;
}
}
/**
* The evidence one cited note offers: the exact bytes the context had -
* the named line range when the pointer carries one (truncated: a
* pointer that names a range names a partial view), the whole file
* otherwise, and past `maxBytes` only the head of the file, decoded
* non-fatally and named truncated. Every failure to read names itself as
* `unavailable` / `not-text` evidence rather than throwing. Exported for
* the bounded-read pins; the ceiling is injectable so a test needs no
* multi-megabyte fixture.
*/
export function evidenceFor(
vault: string,
mark: CitationMark,
maxBytes: number = ANSWER_QUOTE_NOTE_MAX_BYTES,
): AnswerQuoteEvidence {
const absolute = resolveNotePath(vault, mark.path);
if (absolute === null || !existsSync(absolute)) {
return { kind: "unavailable" };
}
let limited: boolean;
try {
const stat = statSync(absolute);
if (!stat.isFile()) return { kind: "unavailable" };
limited = stat.size > maxBytes;
} catch {
return { kind: "unavailable" };
}
let whole: string;
try {
if (limited) {
const fd = openSync(absolute, "r");
try {
// Non-fatal: a ceiling cut can split a multi-byte character, and
// a valid UTF-8 note must not read as not-text for it.
whole = new TextDecoder("utf-8").decode(readWindow(fd, 0, maxBytes));
} finally {
closeSync(fd);
}
} else {
whole = new TextDecoder("utf-8", { fatal: true }).decode(readFileSync(absolute));
}
} catch {
return { kind: "not-text" };
}
if (mark.startLine === undefined || mark.endLine === undefined) {
return { kind: "text", text: whole, truncated: limited };
}
// A pointer that names a line range past the ceiling names lines the
// bounded read did not fetch: refuse the evidence rather than serve a
// slice of the prefix as if it were the named range.
if (limited) return { kind: "unavailable" };
const lines = whole.split("\n");
const slice = lines.slice(mark.startLine - 1, mark.endLine).join("\n");
return { kind: "text", text: slice, truncated: true };
}
// ----- the injection ledger's candidate notes ------------------------------
/**
* One candidate note view the ledger offers as evidence: the note path,
* the lines the injection named when it delivered only a range, the
* phase whose ledger offered it, and whether the injection delivered
* that note truncated (a clipped body is evidence of the delivered
* prefix only).
*/
interface LedgerCandidate {
readonly path: string;
readonly startLine?: number;
readonly endLine?: number;
readonly phase: AnswerQuoteCheckPhase;
readonly truncated?: boolean;
}
/** Answer order for candidate views: by path, then by named range. */
function compareCandidates(
a: { readonly path: string; readonly startLine?: number; readonly endLine?: number },
b: { readonly path: string; readonly startLine?: number; readonly endLine?: number },
): number {
if (a.path !== b.path) return a.path < b.path ? -1 : 1;
return (a.startLine ?? 0) - (b.startLine ?? 0) || (a.endLine ?? 0) - (b.endLine ?? 0);
}
/**
* The dedup key of one candidate view: the path, plus any range it names.
* Takes the shape both the ledger candidates and the merged views share,
* so the reply-presence fold can key its measured verdicts by it too.
*/
function candidateKey(candidate: {
readonly path: string;
readonly startLine?: number;
readonly endLine?: number;
}): string {
return candidate.startLine === undefined || candidate.endLine === undefined
? candidate.path
: `${candidate.path}\0${candidate.startLine}-${candidate.endLine}`;
}
/**
* One merged candidate in the turn's evidence pool: the note view plus
* every phase whose ledger offered it. The phases are the finding's
* attribution - a miss is reported only when a phase that offered the
* deciding evidence is itself running, and enforced only when one of
* those phases enforces.
*/
interface MergedCandidate {
readonly path: string;
readonly startLine?: number;
readonly endLine?: number;
readonly truncated?: boolean;
readonly phases: ReadonlyArray<AnswerQuoteCheckPhase>;
}
/**
* Merge candidate view groups, per note path: a whole-file view wins over
* that path's line ranges (the whole note reached context through one of
* the groups), and identical ranges collapse - but several DISTINCT
* ranges of one note all stand, each its own evidence. Collapsing them to
* one range (or to the path) would check a correct quote of an earlier
* range against only the latest one and report a miss the turn's
* evidence actually refutes. A merged view carries the union of the
* offering phases and the union of their truncation flags. Sorted by
* path, then range.
*/
function mergeCandidateViews(
groups: ReadonlyArray<ReadonlyArray<LedgerCandidate>>,
): ReadonlyArray<MergedCandidate> {
const whole = new Map<string, Set<AnswerQuoteCheckPhase>>();
const wholeTruncated = new Set<string>();
const ranges = new Map<
string,
{ candidate: LedgerCandidate; phases: Set<AnswerQuoteCheckPhase> }
>();
for (const group of groups) {
for (const candidate of group) {
if (candidate.startLine === undefined || candidate.endLine === undefined) {
const phases = whole.get(candidate.path) ?? new Set<AnswerQuoteCheckPhase>();
phases.add(candidate.phase);
whole.set(candidate.path, phases);
if (candidate.truncated === true) wholeTruncated.add(candidate.path);
} else {
const key = candidateKey(candidate);
const entry = ranges.get(key);
if (entry === undefined) {
ranges.set(key, { candidate, phases: new Set([candidate.phase]) });
} else {
entry.phases.add(candidate.phase);
if (candidate.truncated === true)
entry.candidate = { ...entry.candidate, truncated: true };
}
}
}
}
const mergedRanges = [...ranges.values()]
.filter(({ candidate }) => !whole.has(candidate.path))
.map(({ candidate, phases }) => ({
path: candidate.path,
...(candidate.startLine !== undefined ? { startLine: candidate.startLine } : {}),
...(candidate.endLine !== undefined ? { endLine: candidate.endLine } : {}),
...(candidate.truncated === true ? { truncated: true } : {}),
phases: [...phases],
}));
const mergedWhole = [...whole.entries()]
.toSorted(([a], [b]) => (a < b ? -1 : 1))
.map(([path, phases]) => ({
path,
...(wholeTruncated.has(path) ? { truncated: true } : {}),
phases: [...phases],
}));
return [...mergedRanges, ...mergedWhole].toSorted(compareCandidates);
}
/**
* Note path + line range one recall ledger key names. Recall keys render
* `<origin>:<vault-relative path>#L<start>-L<end>` (`recallInjectNoteKey`),
* where the origin is a search-origin label
* (`src/core/brain/portability/origins.ts`): the bare `local` of the
* active vault, or a kind-namespaced origin whose label carries a slash -
* `profile/<name>`, `source/<alias>` - for a note recalled from another
* vault. Splitting on the LAST colon before the `#L` anchor puts the
* whole label on the left, slash-bearing or not, and the path - always
* carrying a `/` - on the right; the label is dropped. The cross-origin
* note itself still cannot be read under the active vault - it is
* evidence outside this vault - so its spans resolve as
* `note-unavailable` deliberately, never as an all-clear.
*/
function recallKeyCandidate(
key: string,
): { readonly path: string; readonly startLine: number; readonly endLine: number } | null {
const hash = key.lastIndexOf("#L");
if (hash === -1) return null;
const range = /^L(\d+)-L(\d+)$/.exec(key.slice(hash + 1));
if (range === null) return null;
const body = key.slice(0, hash);
const colon = body.lastIndexOf(":");
const label = colon === -1 ? null : body.slice(0, colon);
const rest = colon === -1 ? body : body.slice(colon + 1);
// `<origin>:<path>`: the right side is a vault-relative path, whatever
// the left side looks like. A colon with no slash on either side is
// not a recognized key shape and the body stays whole.
const path = rest.includes("/") || (label !== null && label.includes("/")) ? rest : body;
return { path, startLine: Number(range[1]), endLine: Number(range[2]) };
}
/** `.md` path tokens in one ledger member string, without line ranges. */
function pathTokens(member: string): ReadonlyArray<string> {
return [...member.matchAll(PATH_TOKEN_RE)].map((match) => match[0]);
}
/**
* The candidate note paths of one phase's ledger: recall keys parse to
* path + line range, the active ledger names paths directly, the queued
* re-delivery parts are prose scanned for path tokens, and the sub-agent
* delivery ledger names the paths the delivered payloads were built from
* (a row recorded before that field existed contributes nothing - an old
* ledger row is silence for this phase, never an error). Sorted,
* deduplicated; empty when the session has no ledger (a sessionless host
* has none at all).
*/
function ledgerCandidates(
vault: string,
sessionId: string | null,
phase: AnswerQuoteCheckPhase,
nowMs: number,
): ReadonlyArray<LedgerCandidate> {
if (sessionId === null) return [];
// Several DISTINCT line ranges of one note all stand: each names the
// part of the note that actually reached context, and collapsing them
// to the last range would check a correct quote of an earlier range
// against the wrong lines. Whole-file views (no range) are deduped by
// path; the merge across phases applies the whole-wins-over-ranges
// rule (mergeCandidateViews).
const seen = new Set<string>();
const candidates: LedgerCandidate[] = [];
const add = (candidate: Omit<LedgerCandidate, "phase">): void => {
const key = candidateKey(candidate);
if (seen.has(key)) return;
seen.add(key);
candidates.push({ ...candidate, phase });
};
if (phase === "recall") {
for (const key of readRecallInjected(vault, sessionId, nowMs)) {
const parsed = recallKeyCandidate(key);
if (parsed === null) continue;
add({ path: parsed.path, startLine: parsed.startLine, endLine: parsed.endLine });
}
}
if (phase === "active") {
for (const path of readActiveEmittedPaths(vault, sessionId, nowMs)) {
add({ path });
}
const parts = readHookStamp(vault, sessionId, LEDGER_KEY_REGROUND, nowMs)?.data?.["parts"];
if (Array.isArray(parts)) {
for (const part of parts) {
if (typeof part !== "string") continue;
for (const path of pathTokens(part)) add({ path });
}
}
}
if (phase === "subagent") {
for (const delivered of readSubagentDeliveredPaths(vault, sessionId, nowMs)) {
add(
typeof delivered === "string"
? { path: delivered }
: { path: delivered.path, truncated: delivered.truncated },
);
}
}
return candidates.toSorted(compareCandidates);
}
// ----- the check ------------------------------------------------------------
/** One candidate's verdict for one span, kept for the reply-presence fold. */
interface SpanCandidateOutcome {
readonly candidate: MergedCandidate;
readonly verdict: AnswerQuoteVerdict;
}
/** One span's outcome under the resolved evidence, inside the budget. */
interface SpanOutcome {
readonly verdict: AnswerQuoteVerdict;
/**
* The span as the check module previews it - length-capped, code-point
* safe. Findings render only this form, never the raw span: a span is
* answer text, and the annotation's line structure is the hook's voice.
*/
readonly preview: string;
/**
* The phases of the candidates that decided this outcome - the verdict
* source when the span verified, every candidate checked when it did
* not. A finding is reported only when a running phase is among them,
* and enforced only when one of those running phases enforces.
*/
readonly decidingPhases: ReadonlyArray<AnswerQuoteCheckPhase>;
/**
* The verdicts the reply-presence fold records for this span, in check
* order (t_f8510c55). A span that verified somewhere records ONLY the
* verifying candidate's outcome - the span belongs to the note that
* carries it, and a candidate that missed it before the walk reached
* the verifier did not measure the span in any sense worth reporting.
* A span that verified nowhere records every candidate's miss. A
* candidate left unmeasured appears here for no span, which the fold
* reads as `absent`; a candidate the budget cut reads
* `note-unavailable`, never `absent`, so an unspent budget can never
* masquerade as an untouched note.
*/
readonly candidateOutcomes: ReadonlyArray<SpanCandidateOutcome>;
}
/** One span's verdict under the resolved evidence, inside the budget. */
function checkSpan(
span: QuotedSpan,
marks: ReadonlyArray<CitationMark>,
candidates: ReadonlyArray<MergedCandidate>,
vault: string,
deadline: number,
): SpanOutcome {
// The cited note: the nearest mark before the span, else the first one
// after it. A mark inside the span is span content, never a citation.
const before = marks.filter((mark) => mark.at < span.open);
const after = marks.filter((mark) => mark.at > span.close);
if (before.length > 0 || after.length > 0) {
const mark = before.length > 0 ? before[before.length - 1]! : after[0]!;
const { outcomes } = checkAnswerQuotes({
spans: [span.inner],
evidence: evidenceFor(vault, mark),
});
// The span was MEASURED against the cited note's evidence, so every
// ledger candidate naming the cited note records the outcome -
// citing an injected note is the most explicit way to surface it,
// and an empty outcome list here would fold that note `absent`
// ("injected, never surfaced") against what the reply just did.
// A mark with a line range rides only on the candidate whose
// delivered view is that same range; a whole-note candidate matches
// any citation of its note.
const cited = candidates.filter(
(candidate) =>
candidate.path === mark.path &&
(mark.startLine === undefined ||
// A whole-note candidate is the note itself: any citation of
// its path names content it delivered. (The merge also folds
// every range of a path away once the whole note was
// delivered, so a range-only match would miss it.)
candidate.startLine === undefined ||
candidateKey(candidate) === candidateKey(mark)),
);
return {
verdict: outcomes[0]!.verdict,
preview: outcomes[0]!.span,
decidingPhases: [],
candidateOutcomes: cited.map((candidate) => ({
candidate,
verdict: outcomes[0]!.verdict,
})),
};
}
if (candidates.length === 0) {
return {
verdict: mergeAnswerQuoteVerdicts([]),
preview: previewAnswerQuoteSpan(span.inner),
decidingPhases: [],
candidateOutcomes: [],
};
}
const verdicts: AnswerQuoteVerdict[] = [];
const decidingPhases: AnswerQuoteCheckPhase[] = [];
const candidateOutcomes: SpanCandidateOutcome[] = [];
let preview = previewAnswerQuoteSpan(span.inner);
for (const [index, candidate] of candidates.entries()) {
if (Date.now() > deadline) {
// Budget spent with unread candidates left: the check did not
// finish, so it never reports a readable-miss verdict. Every
// unread candidate is recorded as `note-unavailable` for this
// span - checked-and-unresolved, never silently untouched.
return {
verdict: ANSWER_QUOTE_VERDICT.noteUnavailable,
preview,
decidingPhases,
candidateOutcomes: [
...candidateOutcomes,
...candidates.slice(index).map((unread) => ({
candidate: unread,
verdict: ANSWER_QUOTE_VERDICT.noteUnavailable,
})),
],
};
}
const mark: CitationMark = {
at: -1,
path: candidate.path,
...(candidate.startLine !== undefined ? { startLine: candidate.startLine } : {}),
...(candidate.endLine !== undefined ? { endLine: candidate.endLine } : {}),
};
let evidence = evidenceFor(vault, mark);
// The injection delivered only a prefix of this note: evidence is the
// delivered prefix, whatever the file holds today. A miss under
// clipped evidence is `source-truncated`, never a readable miss - a
// truncated source never acquits a span, and never convicts one the
// delivered text cannot judge.
if (candidate.truncated === true && evidence.kind === "text") {
evidence = { ...evidence, truncated: true };
}
const { outcomes } = checkAnswerQuotes({
spans: [span.inner],
evidence,
});
const verdict = outcomes[0]!.verdict;
preview = outcomes[0]!.span;
verdicts.push(verdict);
candidateOutcomes.push({ candidate, verdict });
for (const phase of candidate.phases) decidingPhases.push(phase);
if (verdict === ANSWER_QUOTE_VERDICT.verified) break;
}
const merged = mergeAnswerQuoteVerdicts(verdicts);
// A span that verified somewhere belongs to the note it verified
// against: only that candidate's outcome is recorded. The misses the
// walk accumulated before reaching the verifier were measurements of
// the span against evidence that could not carry it - recording them
// would make an unrelated note's verdict depend on whether its path
// sorts before or after the verifying one. Per-candidate misses stay
// only for spans that verified nowhere, where every miss is the
// span's own history.
const recordedOutcomes =
merged === ANSWER_QUOTE_VERDICT.verified
? candidateOutcomes.filter((outcome) => outcome.verdict === ANSWER_QUOTE_VERDICT.verified)
: candidateOutcomes;
return {
verdict: merged,
preview,
decidingPhases,
candidateOutcomes: recordedOutcomes,
};
}
/**
* The per-note presence verdicts of one checked turn (t_f8510c55), one
* row per candidate the injection ledger offered: `verified` when at
* least one quoted span of the reply checked out against the note;
* otherwise the strongest miss verdict across the spans that measured
* it - the check module's own merge ladder, so degradation still
* outranks a readable miss per note exactly as it does per turn;
* {@link ANSWER_QUOTE_VERDICT.absent} for a note no span was ever
* measured against - injected into context, never surfaced in the
* answer, the row this record exists to surface; and
* {@link ANSWER_QUOTE_VERDICT.noteUnavailable} for a note no span
* measured while the budget was exhausted - the transcript went unread
* past the cut, which is not evidence the note went untouched, so the
* fold refuses to spend `absent` on it. A span that verified somewhere
* measured only the note that carries it ({@link checkSpan} records the
* verifying candidate alone), so a note's verdict is a fact about the
* reply, never about where its path sorts. Rows carry identifiers and
* verdicts only; no answer text rides the record.
*/
function foldReplyPresence(
candidates: ReadonlyArray<MergedCandidate>,
outcomes: ReadonlyArray<SpanCandidateOutcome>,
budgetExhausted: boolean,
replyRead: boolean,
): ReadonlyArray<Record<string, unknown>> {
const measured = new Map<string, AnswerQuoteVerdict[]>();
for (const outcome of outcomes) {
const key = candidateKey(outcome.candidate);
const verdicts = measured.get(key);
if (verdicts === undefined) measured.set(key, [outcome.verdict]);
else verdicts.push(outcome.verdict);
}
return candidates.map((candidate) => {
const verdicts = measured.get(candidateKey(candidate));
return {
path: candidate.path,
...(candidate.startLine !== undefined ? { start_line: candidate.startLine } : {}),
...(candidate.endLine !== undefined ? { end_line: candidate.endLine } : {}),
verdict:
verdicts === undefined
? unmeasuredPresenceVerdict(budgetExhausted, replyRead)
: mergeAnswerQuoteVerdicts(verdicts),
};
});
}
/**
* The verdict for a note no span ever measured. When the walk's budget
* ran out, or the reply text was never readable in the first place,
* nothing was measured FOR A REASON - `note-unavailable`, the
* checked-and-unresolved answer - never `absent`, which claims the reply
* had every chance to touch the note and did not.
*/
function unmeasuredPresenceVerdict(
budgetExhausted: boolean,
replyRead: boolean,
): AnswerQuoteVerdict {
if (budgetExhausted || !replyRead) return ANSWER_QUOTE_VERDICT.noteUnavailable;
return ANSWER_QUOTE_VERDICT.absent;
}
/** `origin` label of the annotation's framing line for the quoted spans. */
const QUOTE_CHECK_FRAMING_ORIGIN = "quoted-answer-spans";
/**
* One rendered finding line. The span renders neutralized first - the
* structural strip (control/bidi/zero-width, delimiter escape) shared
* with every other untrusted lane, so a span's invisible machinery can
* never ride into the annotation - then flattened - CR/LF and whitespace
* runs collapsed to single spaces, inside the check module's preview cap
* - so answer text can never introduce annotation-shaped lines of its own.
*/
function findingLine(span: string, verdict: AnswerQuoteVerdict): string {
return `- [${verdict}] "${neutralizeUntrustedText(span).replace(/\s+/g, " ").trim()}"`;
}
/** One unverified span, as the annotation and the enforce trail name it. */
interface AnswerQuoteSpanFinding {
readonly span: string;
readonly verdict: AnswerQuoteVerdict;
}
/** Duplicate findings collapse to their first occurrence, answer order kept. */
function dedupeFindings(
findings: ReadonlyArray<AnswerQuoteSpanFinding>,
): ReadonlyArray<AnswerQuoteSpanFinding> {
const seen = new Set<string>();
const unique: AnswerQuoteSpanFinding[] = [];
for (const finding of findings) {
const key = findingLine(finding.span, finding.verdict);
if (seen.has(key)) continue;
seen.add(key);
unique.push(finding);
}
return unique;
}
/**
* The findings one annotation - and one enforce event - render: the
* first {@link ANSWER_QUOTE_MAX_FINDINGS}, answer order kept. The header
* and the enforce counters still state the true total.
*/
function listedFindings(
findings: ReadonlyArray<AnswerQuoteSpanFinding>,
): ReadonlyArray<AnswerQuoteSpanFinding> {
return findings.slice(0, ANSWER_QUOTE_MAX_FINDINGS);
}
/**
* The annotation: exactly one line block listing the unverified spans
* with their verdicts, duplicate-free, in answer order, under the
* findings cap. The hook's own trusted lines - the count header, the
* overflow line and the advisory footer - come FIRST, because the
* records-not-instructions framing line hands everything FOLLOWING it
* to the reader as data: the frame is the last trusted line the
* annotation emits, and the spans beneath it are answer text.
*/
function annotation(findings: ReadonlyArray<AnswerQuoteSpanFinding>): string {
const listed = listedFindings(findings);
const lines = [
`Open Second Brain quote check: ${findings.length} quoted span(s) were not found in the notes this turn had:`,
];
if (listed.length < findings.length) {
lines.push(`... and ${findings.length - listed.length} more unverified span(s) not listed.`);
}
lines.push(
"Advisory only; the answer is not blocked. Verify the quotes against the note, or reword.",
untrustedFramingHeader(QUOTE_CHECK_FRAMING_ORIGIN),
);
for (const finding of listed) lines.push(findingLine(finding.span, finding.verdict));
return lines.join("\n");
}
async function main(): Promise<void> {
let payload;
try {
payload = asHookPayload(await readHookInput());
} catch (err) {
// An unparseable payload is a host fault: one audit line, the same
// prefix as every other error arm, and never a block.
process.stderr.write(`${AUDIT_PREFIX} ${err instanceof Error ? err.message : String(err)}\n`);
return;
}
// Once per turn: the runtime already continued this turn on a Stop
// hook's output, so re-annotating would loop.
if (payload.stop_hook_active === true) return;
const transcriptPath = payload.transcript_path;
if (typeof transcriptPath !== "string" || transcriptPath.length === 0) return;
// A transcript the host has not created yet is a fresh session, not an
// error: silence, like every other empty-handed arm.
if (!existsSync(transcriptPath)) return;
// With no vault the hook does its store-side part (design D14, task 2.10).
const target = resolveHookTarget();
if (target === null) return;
const vault = target.vault;
const sessionId = isRealSessionId(payload.session_id) ? payload.session_id : null;
const started = Date.now();
const deadline = started + ANSWER_QUOTE_BUDGET_MS;
const now = started;
const configPath = brainConfigPath(vault);
const modes: Readonly<Record<AnswerQuoteCheckPhase, AnswerQuoteCheckMode>> = {
recall: resolveAnswerQuoteCheckRecall(configPath),
active: resolveAnswerQuoteCheckActive(configPath),
subagent: resolveAnswerQuoteCheckSubagent(configPath),
};
// Every phase `off` reports nothing and enforces nothing, so the run
// pays no ledger read at all: the injection ledgers - whose member
// strings are prose that gets path-scanned - stay unopened.
if (ANSWER_QUOTE_CHECK_PHASES.every((phase) => modes[phase] === "off")) return;
const ledgerNotes: Readonly<Record<AnswerQuoteCheckPhase, ReturnType<typeof ledgerCandidates>>> =
{
recall: ledgerCandidates(vault, sessionId, "recall", now),
active: ledgerCandidates(vault, sessionId, "active", now),
subagent: ledgerCandidates(vault, sessionId, "subagent", now),
};
// A phase contributes evidence when its injection happened (recall's
// gate is the recall-inject flag; active and subagent have a live
// ledger of their own); its MODE decides only whether a finding the
// phase's evidence decided is reported - and enforced. Building the
// pool from every injected ledger keeps a phase switched to `off` from
// turning its delivered notes into false `[not-in-note]` findings for
// spans another phase still checks.
const gates: Readonly<Record<AnswerQuoteCheckPhase, boolean>> = {
recall: resolveRecallInjectEnabled(),
active: ledgerNotes.active.length > 0,
subagent: ledgerNotes.subagent.length > 0,
};
const running = ANSWER_QUOTE_CHECK_PHASES.filter(
(phase) => gates[phase] && modes[phase] !== "off",
);
if (running.length === 0) return;
const candidates = mergeCandidateViews(
ANSWER_QUOTE_CHECK_PHASES.filter((phase) => gates[phase]).map((phase) => ledgerNotes[phase]),
);
const messages = lastAssistantMessages(transcriptPath);
const findings: Array<AnswerQuoteSpanFinding> = [];
const presenceOutcomes: SpanCandidateOutcome[] = [];
let checked = 0;
let enforceable = 0;
// Set when a deadline comparison cuts the walk: spans never started
// contribute no candidate outcomes, so their candidates would otherwise
// fold as `absent` - a verdict the fold reserves for a note the reply
// had every chance to touch and did not.
let budgetExhausted = false;
outer: for (const [messageIndex, message] of messages.entries()) {
// Before the scans of this message, not only before its spans: the
// span and path scans themselves cost the budget they precede.
if (Date.now() > deadline) {
budgetExhausted = true;
break outer;
}
const scan = findQuoteSpans(message);
if (scan.spans.length === 0) continue;
const marks = citationMarks(message);
for (const span of scan.spans) {
if (Date.now() > deadline) {
budgetExhausted = true;
break outer;
}
checked++;
const quoted: QuotedSpan = {
message: messageIndex,
inner: span.inner,
open: span.open,
close: span.close,
};
const outcome = checkSpan(quoted, marks, candidates, vault, deadline);
presenceOutcomes.push(...outcome.candidateOutcomes);
if (outcome.verdict !== ANSWER_QUOTE_VERDICT.verified) {
// Attribution: the phases whose candidates decided this miss. A
// miss decided only by a phase switched to `off` is not this
// turn's report - the operator disabled that phase's findings,
// and its delivered notes are still evidence for the phases
// that remain on. A span with an explicit citation mark (or no
// candidate at all) is not ledger-attributable: every running
// phase's check covers it, exactly as before the attribution.
const deciding = outcome.decidingPhases.length > 0 ? outcome.decidingPhases : running;
const contributing = deciding.filter((phase) => modes[phase] !== "off");
if (contributing.length === 0) continue;
if (contributing.some((phase) => modes[phase] === "enforce")) enforceable++;
findings.push({ span: outcome.preview, verdict: outcome.verdict });
}
}
}
// The reply-presence record (t_f8510c55): exactly one per checked
// turn, whatever the findings - a turn whose every span verified still
// owes its per-note verdicts, and a note no span touched reads
// `absent`, the row this record exists to surface - except when the
// budget cut the walk or the reply text never arrived, where an
// unmeasured note reads `note-unavailable` (the fold's own doc names
// the distinction: an unmeasured note never reads as an unused one).
// A turn with no injected candidate writes nothing: with no note to
// report on, an empty verdict list would say nothing the absence of a
// record does not say already - and the session id rides every record,
// since the ledger candidates are unreachable without one. Fail-open
// like every arm: a failed append names itself on the audit line and
// the annotation still goes out.
if (candidates.length > 0 && sessionId !== null) {
try {
appendContinuityRecord(vault, {
kind: "reply_presence",
createdAt: isoSecond(new Date()),
payload: {
[CONTINUITY_SESSION_ID_KEY]: sessionId,
checked,
per_note: foldReplyPresence(
candidates,
presenceOutcomes,
budgetExhausted,
messages.length > 0,
),
// The hash binds the verdicts to the exact answer text checked;
// it carries no answer text itself.
...(messages.length > 0
? {
source_hash: createHash("sha256").update(messages.join("\n"), "utf8").digest("hex"),
}
: {}),
},
});
} catch (err) {
process.stderr.write(`${AUDIT_PREFIX} ${err instanceof Error ? err.message : String(err)}\n`);
}
}
const unique = dedupeFindings(findings);
if (unique.length === 0) return;
if (enforceable > 0) {
// Exactly one Brain-log event per turn, best-effort: a failed append
// names itself on the audit line and the annotation still goes out.
// The findings ride the same capped, flattened lines the annotation
// renders; the counter states the true total of the enforceable
// findings - the ones a running `enforce` phase's evidence decided.
try {
appendLogEvent(vault, {
timestamp: isoSecond(new Date()),
// The `note` kind is the Brain log's designated audit-line home;
// the pinned `session-lifecycle` shape belongs to the lifecycle
// capture and is not this event's shape to borrow.
eventType: BRAIN_LOG_EVENT_KIND.note,
agent: resolveAgentName(),
body: {
hook: "answer-quote-check",
phases: running.join(","),
checked: String(checked),
unverified: String(enforceable),
findings: listedFindings(unique).map((finding) =>
findingLine(finding.span, finding.verdict),
),
},
});
} catch (err) {
process.stderr.write(`${AUDIT_PREFIX} ${err instanceof Error ? err.message : String(err)}\n`);
}
}
process.stdout.write(
`${JSON.stringify({
hookSpecificOutput: { hookEventName: "Stop", additionalContext: annotation(unique) },
})}\n`,
);
}
// Run only as the hook process itself (the `o2b-hook` shim execs this
// file), not when the module is imported for its constants in tests.
if (import.meta.main) {
main().catch((err: unknown) => {
// Never deadlock on a hook crash: one stderr audit line, exit 0.
process.stderr.write(`${AUDIT_PREFIX} ${err instanceof Error ? err.message : String(err)}\n`);
});
}