@ramarivera/coding-buddy 0.7.3 → 0.9.0

package/server/hooks/buddy-comment.ts

@@ -1,13 +1,15 @@
 #!/usr/bin/env bun
 
-import { mkdirSync, writeFileSync } from "fs";
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "fs";
 import { join } from "path";
+import { reactionPool } from "./reaction-data.ts";
 import {
   defaultSpawnDetached,
   fileExists,
   isOnCooldown,
   nonNegativeInteger,
   parseHookInput,
+  pickRandom,
   readJsonFile,
   readStdin,
   resolveHookSessionId,
@@ -25,10 +27,29 @@ interface Events {
   [key: string]: unknown;
 }
 
+interface BuddyStatus {
+  species?: unknown;
+  [key: string]: unknown;
+}
+
+interface ReactionFile {
+  source?: string;
+  timestamp?: number;
+  [key: string]: unknown;
+}
+
 const BUDDY_COMMENT_PATTERN = /<!--\s*buddy:\s*([\s\S]*?)\s*-->/g;
 
+/**
+ * Provenance of the reaction the hook wrote. Mirrors server/state.ts
+ * `ReactionSource`; loaded as `none` on legacy files without the field.
+ */
+export type ReactionSource = "comment" | "fallback" | "none";
+
 export interface BuddyCommentResult {
   comment?: string;
+  /** What produced the bubble. `"none"` means the hook ran but wrote nothing. */
+  source: ReactionSource;
   updated: boolean;
 }
 
@@ -41,37 +62,164 @@ export function extractBuddyComment(message: string): string {
   return comment;
 }
 
-export function handleBuddyComment(rawInput: string, runtime: HookRuntime = {}): BuddyCommentResult {
+/**
+ * Tolerate tool-stamped timestamps that are slightly in the future (NTP
+ * step, container/host skew, network-mounted state dir). Larger drifts
+ * are treated as clock-skewed garbage and the hook falls through to
+ * the comment / pool branch.
+ */
+const FUTURE_TIMESTAMP_TOLERANCE_MS = 60_000;
+
+function pickTurnFallback(
+  species: string,
+  runtime: HookRuntime,
+): string | undefined {
+  // The hook context has no stat-modifier inputs; pick from the canned
+  // pool directly rather than calling server/reactions.ts `getReaction`,
+  // which is reserved for the MCP server's tool-call path. This mirrors
+  // the file-type-react / mood-react / react hook convention.
+  const pool = reactionPool(species, "turn");
+  if (pool.length === 0) return undefined;
+  return pickRandom(pool, runtime);
+}
+
+function readSpeciesFromStatus(stateDir: string): string {
+  const status = readJsonFile<BuddyStatus>(join(stateDir, "status.json"));
+  return typeof status?.species === "string" && status.species.length > 0
+    ? status.species
+    : "blob";
+}
+
+/** Atomic write — tmp + rename. */
+function atomicWriteJson(path: string, value: unknown): void {
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync(tmp, JSON.stringify(value, null, 2));
+  renameSync(tmp, path);
+}
+
+function atomicWriteTimestamp(path: string, nowMs: number): void {
+  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
+  writeFileSync(tmp, String(Math.floor(nowMs / 1000)));
+  renameSync(tmp, path);
+}
+
+function readTimestampSeconds(path: string): number {
+  try {
+    const v = Number.parseInt(readFileSync(path, "utf8").trim(), 10);
+    return Number.isFinite(v) ? v : 0;
+  } catch {
+    return 0;
+  }
+}
+
+/**
+ * Did `buddy_react` fire during the current turn?
+ *
+ * The Stop hook is the only place that knows turn boundaries. After each
+ * Stop hook run, we stamp the wall-clock time into
+ * `.last_stop_hook.<sid>` (seconds). A tool-author ed reaction whose
+ * timestamp is more recent than the LAST Stop hook run is by definition
+ * from this turn; leave it alone.
+ *
+ * Wall-clock 60 s freshness windows lose tool reactions on agentic
+ * turns of 90 s–5 min, which are ordinary. This sentinel scales with
+ * turn length, not elapsed time.
+ *
+ * Clock-skew guard: a tool timestamp implausibly in the future (beyond
+ * `FUTURE_TIMESTAMP_TOLERANCE_MS`) is treated as garbage and we fall
+ * through to the comment / pool branch. A future-dated `lastStopRun`
+ * is clamped to `now` so a skewed clock on a prior run does not poison
+ * the comparison.
+ */
+function toolFiredThisTurn(
+  reactionPath: string,
+  stopMarkerPath: string,
+  nowMs: number,
+): boolean {
+  const existing = readJsonFile<ReactionFile>(reactionPath);
+  if (!existing || existing.source !== "tool") return false;
+  const ts = typeof existing.timestamp === "number" ? existing.timestamp : 0;
+  if (ts <= 0) return false;
+  if (ts > nowMs + FUTURE_TIMESTAMP_TOLERANCE_MS) return false;
+  const lastStopSec = readTimestampSeconds(stopMarkerPath);
+  const effectiveLastStopMs = Math.min(lastStopSec * 1000, nowMs);
+  return ts > effectiveLastStopMs;
+}
+
+export function handleBuddyComment(
+  rawInput: string,
+  runtime: HookRuntime = {},
+): BuddyCommentResult {
   const stateDir = resolveHookStateDir(runtime);
-  if (!fileExists(join(stateDir, "status.json"))) return { updated: false };
+  if (!fileExists(join(stateDir, "status.json"))) {
+    return { source: "none", updated: false };
+  }
 
   const input = parseHookInput(rawInput);
-  if (!input) return { updated: false };
+  if (!input) return { source: "none", updated: false };
 
   const assistantMessage = stringField(input, "last_assistant_message");
-  if (!assistantMessage) return { updated: false };
-
-  const comment = extractBuddyComment(assistantMessage);
-  if (!comment) return { updated: false };
+  if (!assistantMessage) return { source: "none", updated: false };
 
   const now = runtime.now?.() ?? Date.now();
   const sid = resolveHookSessionId(runtime);
+  const reactionPath = join(stateDir, `reaction.${sid}.json`);
+  const cooldownFile = join(stateDir, `.last_comment.${sid}`);
+  const stopMarkerFile = join(stateDir, `.last_stop_hook.${sid}`);
   const config = readJsonFile<BuddyConfig>(join(stateDir, "config.json")) ?? {};
   const cooldown = nonNegativeInteger(config.commentCooldown, 30);
-  const cooldownFile = join(stateDir, `.last_comment.${sid}`);
-  if (isOnCooldown(cooldownFile, cooldown, now)) return { updated: false };
+
+  // ─── Don't clobber a buddy_react tool reaction from this turn ───────────
+  if (toolFiredThisTurn(reactionPath, stopMarkerFile, now)) {
+    atomicWriteTimestamp(stopMarkerFile, now);
+    return { source: "none", updated: false };
+  }
+
+  // ─── Cooldown: rate-limit the reaction write AND bookkeeping ──────────
+  // Main ran the turn counter / XP / memory hooks only inside the
+  // "reaction written" branch. Running them unconditionally makes the
+  // XP economy and spawn counts scale with Stop event frequency, which
+  // is wrong.
+  if (isOnCooldown(cooldownFile, cooldown, now)) {
+    atomicWriteTimestamp(stopMarkerFile, now);
+    return { source: "none", updated: false };
+  }
+
+  // ─── Pick a reaction: legacy comment → canned pool → nothing ────────────
+  const commentFromMessage = extractBuddyComment(assistantMessage);
+  let comment: string | undefined;
+  let source: ReactionSource;
+
+  if (commentFromMessage) {
+    comment = commentFromMessage;
+    source = "comment";
+  } else {
+    const species = readSpeciesFromStatus(stateDir);
+    const fallback = pickTurnFallback(species, runtime);
+    if (fallback) {
+      comment = fallback;
+      source = "fallback";
+    } else {
+      atomicWriteTimestamp(stopMarkerFile, now);
+      return { source: "none", updated: false };
+    }
+  }
 
   mkdirSync(stateDir, { recursive: true });
-  writeFileSync(cooldownFile, String(Math.floor(now / 1000)));
-  writeFileSync(
-    join(stateDir, `reaction.${sid}.json`),
-    JSON.stringify({ reaction: comment, timestamp: now, reason: "turn" }),
-  );
 
+  // Bookkeeping fires only when a reaction is actually written (main).
   const eventsFile = join(stateDir, "events.json");
   const events = readJsonFile<Events>(eventsFile) ?? {};
   events.turns = (typeof events.turns === "number" ? events.turns : 0) + 1;
-  writeFileSync(eventsFile, JSON.stringify(events, null, 2));
+  atomicWriteJson(eventsFile, events);
+
+  atomicWriteTimestamp(cooldownFile, now);
+  atomicWriteJson(reactionPath, {
+    reaction: comment,
+    timestamp: now,
+    reason: "turn",
+    source,
+  });
 
   const spawnDetached = runtime.spawnDetached ?? defaultSpawnDetached(runtime);
   spawnDetached("server/award-xp.ts", ["turn"]);
@@ -79,8 +227,9 @@ export function handleBuddyComment(rawInput: string, runtime: HookRuntime = {}):
     assistantMessage,
     stringField(input, "last_user_message"),
   ]);
+  atomicWriteTimestamp(stopMarkerFile, now);
 
-  return { comment, updated: true };
+  return { comment, source, updated: true };
 }
 
 if (import.meta.main) {

package/server/hooks/common.ts

@@ -6,13 +6,23 @@ import { buddyStateDir } from "../path.ts";
 export type JsonObject = Record<string, unknown>;
 
 export interface HookRuntime {
+  clock?: () => HookClock;
   now?: () => number;
   packageRoot?: string;
+  random?: () => number;
   sessionId?: string;
   spawnDetached?: (script: string, args: string[]) => void;
   stateDir?: string;
 }
 
+export interface HookClock {
+  day: number;
+  dayOfWeek: number;
+  hour: number;
+  month: number;
+  nowSeconds: number;
+}
+
 export function parseHookInput(raw: string): JsonObject | null {
   try {
     const value = JSON.parse(raw) as unknown;
@@ -56,6 +66,29 @@ export function nonNegativeInteger(value: unknown, fallback: number): number {
   return fallback;
 }
 
+export function randomIndex(length: number, runtime: HookRuntime = {}): number {
+  return Math.floor((runtime.random?.() ?? Math.random()) * length);
+}
+
+export function pickRandom<T>(values: readonly T[], runtime: HookRuntime = {}): T | undefined {
+  if (values.length === 0) return undefined;
+  return values[randomIndex(values.length, runtime)];
+}
+
+export function hookClock(runtime: HookRuntime = {}): HookClock {
+  if (runtime.clock) return runtime.clock();
+  const nowMs = runtime.now?.() ?? Date.now();
+  const date = new Date(nowMs);
+  const jsDay = date.getDay();
+  return {
+    day: date.getDate(),
+    dayOfWeek: jsDay === 0 ? 7 : jsDay,
+    hour: date.getHours(),
+    month: date.getMonth() + 1,
+    nowSeconds: Math.floor(nowMs / 1000),
+  };
+}
+
 export function isOnCooldown(path: string, cooldownSeconds: number, nowMs: number): boolean {
   try {
     const last = Number.parseInt(readFileSync(path, "utf8").trim(), 10);

package/server/hooks/file-type-react.ts

@@ -0,0 +1,147 @@
+#!/usr/bin/env bun
+
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { fileReactionPool } from "./reaction-data.ts";
+import {
+  fileExists,
+  isOnCooldown,
+  nonNegativeInteger,
+  parseHookInput,
+  pickRandom,
+  readJsonFile,
+  readStdin,
+  resolveHookSessionId,
+  resolveHookStateDir,
+  type HookRuntime,
+} from "./common.ts";
+
+interface BuddyStatus {
+  muted?: unknown;
+  species?: unknown;
+  reaction?: unknown;
+  [key: string]: unknown;
+}
+
+interface FileConfig {
+  commentCooldown?: unknown;
+}
+
+export interface FileTypeReactResult {
+  fileType?: string;
+  reaction?: string;
+  updated: boolean;
+}
+
+const FILE_TYPE_PATTERNS: ReadonlyArray<readonly [string, string]> = [
+  ["readme", "*/README*|*/CHANGELOG*|*/CONTRIBUTING*|*/LICENSE*"],
+  ["package-file", "*/package.json|*/Cargo.toml|*/go.mod|*/go.sum|*/pyproject.toml|*/requirements*.txt"],
+  ["ci-file", "*/.github/workflows/*|*/Jenkinsfile*|*/.gitlab-ci*|*.ci.yml|*.ci.yaml"],
+  ["gitignore", "*/.gitignore|*/.dockerignore|*/.eslintignore|*/.prettierignore|.gitignore|.dockerignore|.eslintignore|.prettierignore"],
+  ["env-file", "*/.env*|.env*"],
+  ["makefile", "*/Makefile*|Makefile*|*.mk"],
+  ["docker-file", "*/Dockerfile*|Dockerfile*|*/docker-compose*|docker-compose*|*.dockerfile"],
+  ["regex-file", "*.regex|*.pattern"],
+  ["css-file", "*.css|*.scss|*.less|*.sass"],
+  ["sql-file", "*.sql|*migration*"],
+  ["lock-file", "*.lock|*/package-lock.json|*/bun.lockb|*/yarn.lock|*/pnpm-lock.yaml"],
+  ["test-file", "*.test.*|*.spec.*|*_test.*|*test_*"],
+  ["doc-file", "*.md|*.rst|*.txt|*.adoc"],
+  ["config-file", "*.json|*.yaml|*.yml|*.toml|*.ini|*.conf"],
+  ["binary-file", "*.png|*.jpg|*.gif|*.woff*|*.ico|*.exe|*.so|*.dylib|*.bin"],
+  ["proto-file", "*.proto|*.graphql|*.gql"],
+  ["lang-python", "*.py"],
+  ["lang-typescript", "*.ts|*.tsx"],
+  ["lang-javascript", "*.js|*.jsx"],
+  ["lang-rust", "*.rs"],
+  ["lang-go", "*.go"],
+  ["lang-java", "*.java"],
+  ["lang-ruby", "*.rb"],
+  ["lang-php", "*.php"],
+  ["lang-c", "*.c|*.h"],
+  ["lang-cpp", "*.cpp|*.hpp"],
+  ["lang-swift", "*.swift"],
+  ["lang-kotlin", "*.kt"],
+  ["lang-haskell", "*.hs"],
+  ["lang-elixir", "*.ex|*.exs"],
+  ["lang-zig", "*.zig"],
+];
+
+function shellGlob(pattern: string): RegExp {
+  let source = "^";
+  for (const character of pattern) {
+    if (character === "*") source += ".*";
+    else if (character === "?") source += ".";
+    else source += character.replace(/[\\^$.*+()[\]{}|]/g, "\\$&");
+  }
+  return new RegExp(`${source}$`);
+}
+
+function matchesAnyPattern(path: string, patterns: string): boolean {
+  return patterns.split("|").some((pattern) => shellGlob(pattern).test(path));
+}
+
+export function fileTypeForPath(filePath: string): string {
+  for (const [fileType, patterns] of FILE_TYPE_PATTERNS) {
+    if (matchesAnyPattern(filePath, patterns)) return fileType;
+  }
+  return "";
+}
+
+function textValue(value: unknown): string {
+  if (typeof value === "string") return value;
+  if (value === null || value === undefined) return "";
+  return typeof value === "object" ? JSON.stringify(value) : String(value);
+}
+
+export function handleFileTypeReact(rawInput: string, runtime: HookRuntime = {}): FileTypeReactResult {
+  const stateDir = resolveHookStateDir(runtime);
+  const statusFile = join(stateDir, "status.json");
+  if (!fileExists(statusFile)) return { updated: false };
+
+  const config = readJsonFile<FileConfig>(join(stateDir, "config.json")) ?? {};
+  const cooldown = nonNegativeInteger(config.commentCooldown, 30);
+  const sid = resolveHookSessionId(runtime);
+  const now = runtime.now?.() ?? Date.now();
+  if (isOnCooldown(join(stateDir, `.last_reaction.${sid}`), cooldown, now)) {
+    return { updated: false };
+  }
+
+  const parsedStatus = readJsonFile<BuddyStatus>(statusFile);
+  const status = parsedStatus ?? {};
+  if (status.muted === true || status.muted === "true") return { updated: false };
+
+  const input = parseHookInput(rawInput);
+  if (!input) return { updated: false };
+  const filePath = textValue(input.file_path);
+  if (!filePath) return { updated: false };
+
+  if ((runtime.random?.() ?? Math.random()) * 100 >= 15) return { updated: false };
+
+  let fileType = fileTypeForPath(filePath);
+  if (!fileType) return { updated: false };
+  if (fileType === "lang-javascript") fileType = "lang-typescript";
+
+  const species = textValue(status.species) || "blob";
+  const reaction = pickRandom(fileReactionPool(species, fileType), runtime);
+  if (!reaction) return { updated: false };
+
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(join(stateDir, `.last_reaction.${sid}`), String(Math.floor(now / 1000)));
+  writeFileSync(
+    join(stateDir, `reaction.${sid}.json`),
+    JSON.stringify({ reaction, timestamp: Math.floor(now / 1000) * 1000, reason: fileType, source: "fallback" }),
+  );
+  if (parsedStatus) writeFileSync(statusFile, JSON.stringify({ ...status, reaction }, null, 2));
+
+  return { fileType, reaction, updated: true };
+}
+
+if (import.meta.main) {
+  try {
+    handleFileTypeReact(await readStdin());
+  } catch {
+    // Claude Code hooks must never fail the turn.
+  }
+  process.exit(0);
+}

package/server/hooks/mood-react.ts

@@ -0,0 +1,107 @@
+#!/usr/bin/env bun
+
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import { moodReactionPool } from "./reaction-data.ts";
+import {
+  fileExists,
+  isOnCooldown,
+  nonNegativeInteger,
+  parseHookInput,
+  pickRandom,
+  readJsonFile,
+  readStdin,
+  resolveHookSessionId,
+  resolveHookStateDir,
+  stringField,
+  type HookRuntime,
+} from "./common.ts";
+
+interface BuddyStatus {
+  muted?: unknown;
+  species?: unknown;
+  reaction?: unknown;
+  [key: string]: unknown;
+}
+
+interface MoodConfig {
+  moodCooldown?: unknown;
+}
+
+interface Events {
+  [key: string]: unknown;
+}
+
+export interface MoodReactResult {
+  mood?: "frustrated" | "happy" | "stuck";
+  reaction?: string;
+  updated: boolean;
+}
+
+const MOOD_PATTERNS: ReadonlyArray<readonly [MoodReactResult["mood"], RegExp]> = [
+  ["frustrated", /\bwtf\b|\bugh\b|\bstupid\b|\bbroken\b|why won.?t|\bcome on\b|\bseriously\b|\bdamn\b|\bhell\b|this sucks|hate this|\bgrr\b|\bargh\b|\bannoying\b|\bfrustrat\b|\bterrible\b|\bhorrible\b|\bworst\b/i],
+  ["happy", /\bnice!?\b|\bworks!?\b|\bawesome\b|\bperfect\b|\bgreat\b|love it|\byay\b|\bsweet\b|\bbeautiful\b|\bamazing\b|hell yes|nailed it|fixed it|\bhell yeah\b|\bfantastic\b/i],
+  ["stuck", /\bstuck\b|\bhelp\b|\bconfused\b|don.?t understand|how do i\b|what does\b|why is\b|i can.?t\b|no idea|\blost\b|\bclueless\b|\bbaffled\b|\bpuzzled\b/i],
+];
+
+export function moodForPrompt(prompt: string): MoodReactResult["mood"] {
+  return MOOD_PATTERNS.find(([, pattern]) => pattern.test(prompt))?.[0];
+}
+
+function incrementEvent(stateDir: string, key: string): void {
+  const eventsFile = join(stateDir, "events.json");
+  const parsedEvents = readJsonFile<Events>(eventsFile);
+  if (!parsedEvents && fileExists(eventsFile)) return;
+  const events = parsedEvents ?? {};
+  events[key] = typeof events[key] === "number" ? Number(events[key]) + 1 : 1;
+  writeFileSync(eventsFile, JSON.stringify(events, null, 2));
+}
+
+export function handleMoodReact(rawInput: string, runtime: HookRuntime = {}): MoodReactResult {
+  const stateDir = resolveHookStateDir(runtime);
+  const statusFile = join(stateDir, "status.json");
+  if (!fileExists(statusFile)) return { updated: false };
+
+  const config = readJsonFile<MoodConfig>(join(stateDir, "config.json")) ?? {};
+  const cooldown = nonNegativeInteger(config.moodCooldown, 60);
+  const sid = resolveHookSessionId(runtime);
+  const now = runtime.now?.() ?? Date.now();
+  if (isOnCooldown(join(stateDir, `.last_mood.${sid}`), cooldown, now)) {
+    return { updated: false };
+  }
+
+  const input = parseHookInput(rawInput);
+  if (!input) return { updated: false };
+  const prompt = stringField(input, "prompt");
+  if (!prompt) return { updated: false };
+
+  const parsedStatus = readJsonFile<BuddyStatus>(statusFile);
+  const status = parsedStatus ?? {};
+  if (status.muted === true || status.muted === "true") return { updated: false };
+
+  const mood = moodForPrompt(prompt);
+  if (!mood) return { updated: false };
+  const species = typeof status.species === "string" ? status.species : "blob";
+  const reaction = pickRandom(moodReactionPool(species, mood), runtime);
+  if (!reaction) return { updated: false };
+
+  mkdirSync(stateDir, { recursive: true });
+  writeFileSync(join(stateDir, `.last_mood.${sid}`), String(Math.floor(now / 1000)));
+  writeFileSync(
+    join(stateDir, `reaction.${sid}.json`),
+    JSON.stringify({ reaction, timestamp: Math.floor(now / 1000) * 1000, reason: mood, source: "fallback" }),
+  );
+  if (parsedStatus) writeFileSync(statusFile, JSON.stringify({ ...status, reaction }, null, 2));
+  incrementEvent(stateDir, `mood_${mood}`);
+
+  return { mood, reaction, updated: true };
+}
+
+if (import.meta.main) {
+  try {
+    handleMoodReact(await readStdin());
+  } catch {
+    // Claude Code hooks must never fail the turn.
+  }
+  process.exit(0);
+}

package/server/hooks/name-react.ts

@@ -0,0 +1,98 @@
+#!/usr/bin/env bun
+
+import { mkdirSync, writeFileSync } from "fs";
+import { join } from "path";
+import {
+  DEFAULT_NAME_REACTIONS,
+  NAME_REACTION_POOLS,
+} from "./reaction-data.ts";
+import {
+  fileExists,
+  parseHookInput,
+  pickRandom,
+  readJsonFile,
+  readStdin,
+  resolveHookSessionId,
+  resolveHookStateDir,
+  type JsonObject,
+  type HookRuntime,
+} from "./common.ts";
+
+interface BuddyStatus {
+  muted?: unknown;
+  name?: unknown;
+  species?: unknown;
+  reaction?: unknown;
+  [key: string]: unknown;
+}
+
+export interface NameReactResult {
+  reaction?: string;
+  updated: boolean;
+}
+
+function promptFromInput(input: JsonObject): string {
+  const direct = input.prompt ?? input.message ?? input.user_message;
+  if (direct !== undefined && direct !== null) {
+    return typeof direct === "string" ? direct : String(direct);
+  }
+
+  const messages = input.messages;
+  if (!Array.isArray(messages) || messages.length === 0) return "";
+  const content = (messages[messages.length - 1] as JsonObject | null)?.content;
+  if (Array.isArray(content)) {
+    const first = content[0];
+    return first && typeof first === "object" ? String((first as JsonObject).text ?? "") : "";
+  }
+  return typeof content === "string" ? content : "";
+}
+
+export function hasNameMention(prompt: string, name: string): boolean {
+  if (!name) return false;
+  try {
+    return new RegExp(`(^|[^a-zA-Z])${name}([^a-zA-Z]|$)`, "i").test(prompt);
+  } catch {
+    return false;
+  }
+}
+
+export function handleNameReact(rawInput: string, runtime: HookRuntime = {}): NameReactResult {
+  const stateDir = resolveHookStateDir(runtime);
+  const statusFile = join(stateDir, "status.json");
+  if (!fileExists(statusFile)) return { updated: false };
+
+  const input = parseHookInput(rawInput);
+  if (!input) return { updated: false };
+  const prompt = promptFromInput(input);
+  if (!prompt) return { updated: false };
+
+  const parsedStatus = readJsonFile<BuddyStatus>(statusFile);
+  const status = parsedStatus ?? {};
+  const name = typeof status.name === "string" ? status.name : "";
+  if (!hasNameMention(prompt, name)) return { updated: false };
+  if (status.muted === true || status.muted === "true") return { updated: false };
+
+  const species = typeof status.species === "string" ? status.species : "blob";
+  const reaction = pickRandom(NAME_REACTION_POOLS[species] ?? DEFAULT_NAME_REACTIONS, runtime);
+  if (!reaction) return { updated: false };
+
+  const now = runtime.now?.() ?? Date.now();
+  const sid = resolveHookSessionId(runtime);
+  mkdirSync(stateDir, { recursive: true });
+  if (parsedStatus) writeFileSync(statusFile, JSON.stringify({ ...status, reaction }, null, 2));
+  writeFileSync(
+    join(stateDir, `reaction.${sid}.json`),
+    JSON.stringify({ reaction, timestamp: Math.floor(now / 1000) * 1000, reason: "name", source: "fallback" }),
+  );
+
+  return { reaction, updated: true };
+}
+
+if (import.meta.main) {
+  try {
+    handleNameReact(await readStdin());
+  } catch {
+    // Claude Code hooks must never fail the turn.
+  }
+  process.exit(0);
+}