Hooks That Keep Agents Inside the Lines

/**
* Two events, one script: put the open questions in front of the model at the
* moment they matter.
*
* `SessionStart` injects the blocking questions, once, when a session begins.
* `UserPromptSubmit` injects a question only when the prompt uses one of its
* trigger words, on every prompt, for the life of the session. A list shown
* once at startup is forgotten twenty turns later; a question that arrives in
* the turn that touches its subject is read.
*
* This hook is bookkeeping. It never blocks, it never decides, and every
* failure path exits 0 having printed nothing on stdout. See
* docs/decisions/0137.
*
* Reads: knowledge-base/_questions.md. Writes: nothing.
*/

// ... imports; REPO_ROOT and KB_DIR resolved from import.meta.url, never cwd ...

/**
* The trigger table. This is data, and it is yours to edit, add a row when you
* file a question people keep re-asking. See docs/decisions/0142.
*
* `when` is a list of lower-cased phrases matched against the prompt as plain
* substrings; no regex, so a phrase with a dot or a bracket in it means the dot
* or the bracket. `question` is a substring of the question's line in
* `_questions.md`, which is what ties the row to the question rather than
* copying it: the file stays the one place the text lives, and a row whose
* `question` matches nothing quietly injects nothing.
*/
const TRIGGERS = [
{ when: ["claude_config_dir", "config directory"], question: "CLAUDE_CONFIG_DIR" },
{ when: ["concurrent", "at the same time", "two agents"], question: "two or more SDK subprocesses" },
];

/** Sections of `_questions.md` a trigger match is allowed to draw from. */
const TRIGGERABLE_SECTIONS = ["blocking", "open"];

// ... main() reads stdin, parses the payload, and routes on hook_event_name ...

function main() {
let data;
try {
  data = JSON.parse(readStdinSync());
} catch (error) {
  // Fail open. A hook that cannot read its own input has nothing to say, and
  // saying it on stdout would corrupt the JSON channel for no gain.
  return bail("could not parse the hook payload", error);
}

const event = data?.hook_event_name;
if (event === "SessionStart") return sessionStart(data);
if (event === "UserPromptSubmit") return userPromptSubmit(data);
return bail(`not wired for ${event ?? "an unnamed event"}`);
}

/** SessionStart: the blocking questions, once per session. */
function sessionStart(data) {
// `source` is one of startup, resume, clear, compact, fork. Compaction starts
// a "session" too, so a naive injector re-injects its whole payload after
// every compaction, and the context it was saving is the context it spends.
// The same guard can be written as a matcher group per source in the config
// ("matcher": "startup|resume|clear|fork"), which keeps the process from
// spawning at all; it is read here instead so that one handler entry covers
// every source and this rule stays visible next to the reason for it. See docs/decisions/0144.
if (data?.source === "compact") return;

const questions = read(KB_DIR);
if (!questions) return;

const blocking = questions.blocking ?? [];
if (blocking.length === 0) return; // Nothing blocking is not a message worth sending.

emit("SessionStart", [
  "Blocking questions from knowledge-base/_questions.md, work is stopped until each is answered:",
  ...blocking.map((line) => `- ${line}`),
].join("\n"));
}

/** UserPromptSubmit: only the questions this prompt just walked into. */
function userPromptSubmit(data) {
const prompt = typeof data?.prompt === "string" ? data.prompt.toLowerCase() : "";
if (prompt === "") return;

const questions = read(KB_DIR);
if (!questions) return;

const pool = TRIGGERABLE_SECTIONS.flatMap((section) => questions[section] ?? []);
const matched = [];
for (const row of TRIGGERS) {
  if (!row.when.some((phrase) => prompt.includes(phrase.toLowerCase()))) continue;
  for (const line of pool) {
    if (line.includes(row.question) && !matched.includes(line)) matched.push(line);
  }
}
if (matched.length === 0) return; // No trigger, no injection. Silence is the common case.

emit("UserPromptSubmit", [
  "Open questions this prompt touches, from knowledge-base/_questions.md:",
  ...matched.map((line) => `- ${line}`),
].join("\n"));
}

/**
* Print one `additionalContext` payload for the event that actually fired.
*
* `hookEventName` must name the event this run was invoked for. A SessionStart
* payload emitted from a UserPromptSubmit run is not an error anywhere: the
* harness reads the name, sees it does not match the event in flight, discards
* the whole object, and says nothing. The hook runs, exits 0, prints what looks
* like a correct payload, and injects nothing, which is why the name is passed
* in from the caller here rather than defaulted, and why both call sites are
* one line below the branch that knows which event it is in.
*/
function emit(hookEventName, additionalContext) {
process.stdout.write(JSON.stringify({
  hookSpecificOutput: { hookEventName, additionalContext },
}));
}

// ... read() parses _questions.md into sections; bail() writes stderr only ...

/**
* Stop: refuse to end a turn that changed files and filed nothing.
*
* This is the one hook here that blocks, and a hook that blocks has four things
* to get right or it becomes either a loop or a nag:
*
* 1. It never blocks a continuation it caused itself (`stop_hook_active`).
* 2. It examines a round exactly once, by remembering how far into the
*    transcript it has already read (a byte offset in a sidecar file).
* 3. It fails open on every error. A bookkeeping hook that cannot read its own
*    inputs lets the turn end; the cost of a missed reminder is a reminder.
* 4. It says nothing when nothing changed.
*
* "Was anything filed" is answered from file modification times under
* knowledge-base/, not from the transcript, because a heredoc write, a
* subagent's write and an editor's write are all invisible to tool-use
* inspection and all count as filing. See docs/decisions/0138 through 0140.
*
* Declared in .claude/settings.json, deliberately not in the plugin manifest:
* docs/decisions/0141.
*/

// ... imports; WRITING_TOOLS is Write/Edit/MultiEdit/NotebookEdit; REPO_ROOT and
//     KB_DIR from import.meta.url; STATE_DIR rides WORKBENCH_APP_DATA and falls
//     back to the temp directory (docs/decisions/0139) ...

function main() {
let data;
try {
  data = JSON.parse(readStdinSync());
} catch (error) {
  return bail("could not parse the hook payload", error);
}

// Constraint 1. `stop_hook_active` is true when this turn is only still
// running because a Stop hook blocked it. Blocking again here is the infinite
// self-block: Claude finishes, the hook blocks, Claude finishes, the hook
// blocks. The harness caps that at eight consecutive blocks and then ends the
// turn anyway, so the failure is eight wasted turns rather than a hang, and
// eight wasted turns is still the whole cost of one missing line.
if (data?.stop_hook_active) return;

const transcript = data?.transcript_path;
if (typeof transcript !== "string" || transcript === "") {
  return bail("no transcript_path on the payload");
}

const statePath = sidecarFor(data?.session_id);
const state = readState(statePath);

let size;
try {
  size = statSync(transcript).size;
} catch (error) {
  // Constraint 3. No transcript, no evidence, no block.
  return bail(`could not stat ${transcript}`, error);
}

// Constraint 2. Everything before `offset` was examined at an earlier Stop.
// A shorter file than the offset is a different file under the same path, so
// the only honest offset for it is the beginning.
const offset = state.offset > size ? 0 : state.offset;
const roundStartMs = state.checkedAtMs;

let slice;
try {
  slice = readRange(transcript, offset, size);
} catch (error) {
  return bail(`could not read ${transcript}`, error);
}

// Write the boundary forward before deciding anything. This is what makes
// "block at most once per round" structural rather than a counter: the next
// Stop reads from here, sees the round it already judged as zero new bytes,
// and has nothing to judge.
writeState(statePath, { offset: size, checkedAtMs: Date.now() });

if (offset === size) return; // Nothing new since the last look.

if (roundStartMs === null) {
  // The first Stop of a session has no earlier boundary, so there is no
  // window in which a file could have been filed. It sets the boundary and
  // lets the turn end rather than judging a round it cannot measure.
  return;
}

const changed = changedPaths(slice);
if (changed.length === 0) return; // Constraint 4. Nothing changed, so nothing to say.

let filedAtMs;
try {
  filedAtMs = newestMtimeMs(KB_DIR);
} catch (error) {
  return bail(`could not read ${KB_DIR}`, error);
}
if (filedAtMs > roundStartMs) return; // Something was filed this round. Done.

process.stderr.write(`${reason(changed)}\n`);
process.exit(2); // On Stop, exit 2 is what keeps the turn going, and stderr is the instruction.
}

// ... reason() names the first changed paths and counts the rest; changedPaths()
//     reads tool_use blocks from the slice; newestMtimeMs() walks knowledge-base/
//     for the ground truth, skipping the per-machine agents/ scratchpads ...

{
"hooks": {
  "Stop": [
    {
      "hooks": [
        {
          "type": "command",
          "command": "node",
          "args": ["${CLAUDE_PROJECT_DIR}/tools/hooks/enforce-capture.mjs"],
          "timeout": 15
        }
      ]
    }
  ]
}
}