Skip to content

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
9.8 KB
Raw Blame
/**
 * Tool-name classifiers shared by the PostToolUse reminder and the Stop
 * guardrail. Names match what Claude Code and Codex actually put on the
 * wire (verified against live transcripts under `~/.claude/projects/**`
 * and `~/.codex/sessions/**`).
 *
 * Why a single shared module: the guardrail's correctness rests on
 * counting the same set of names that the PostToolUse reminder fires
 * for, and the same set of names that count as logging. Drifting these
 * lists into separate hook scripts would let the guardrail block on a
 * tool the reminder never warned about, or skip a log call the user
 * actually made.
 */

import type { ToolCall } from "./transcript.ts";

// Canonical tool names that mutate files across runtimes.
//   Claude Code: `Write`, `Edit`, `MultiEdit` (native tools — no
//   `mcp__…__` prefix in transcripts).
//   Codex:       `apply_patch` (custom_tool_call wrapping diffs).
//   Grok Build:  `search_replace` (grok's own file-edit tool, the name
//                it aliases Claude's Edit/Write/MultiEdit to and the name
//                that appears in its hook payload and session transcript).
//
// Codex also supports Edit/Write *aliases* in matchers, but the actual
// `name` field in the transcript is always `apply_patch` for file
// edits done through it; we still accept Edit/Write to defend against
// a future runtime that mirrors the matcher alias into the call name.
const NATIVE_ARTIFACT_NAMES = new Set<string>([
  "Write",
  "Edit",
  "MultiEdit",
  "apply_patch",
  "search_replace",
]);

// Tool-name suffixes that count as "the agent logged this turn",
// regardless of any runtime-injected MCP prefix.
//
// §32 (v0.10.8) retires `event_log_append` and adds `brain_note` as
// the third Brain-native writer (narrative milestones that fit
// neither feedback nor apply-evidence). The set is now
// `brain_feedback` / `brain_apply_evidence` / `brain_note`; any of
// them landing in a turn that produced a durable artifact clears the
// stop guardrail.
//
// Names appear bare in Codex transcripts and decorated as
// `mcp__plugin_<plugin>_<server>__<name>` or `mcp__<server>__<name>`
// in Claude Code transcripts. The regex anchors on either string
// start or a `__` separator so a future prefix change keeps working
// without an emergency patch.
const BRAIN_EVENT_NAME_SUFFIX = /(?:^|__)(brain_feedback|brain_apply_evidence|brain_note)$/;

// Bash command shape that counts as a brain-event call from the CLI.
// Keep this anchored to command boundaries rather than raw substrings:
// generated text like `echo "o2b brain note ..."` must not suppress the
// guardrail. Spawning the MCP server (`o2b mcp …`) does NOT log on its
// own, so it stays out of the matcher — only the explicit event-emitting
// commands are in.
//
// §32 (v0.10.8) drops `o2b append-event` and `vault-log` — those
// still work for human / cron use, but they target the deprecated
// `Daily/` surface and no longer count as a Brain-side event.
const SHELL_ASSIGNMENT = String.raw`[A-Za-z_][A-Za-z0-9_]*=(?:"[^"]*"|'[^']*'|\S+)`;
const BRAIN_EVENT_BASH_COMMAND_RE = new RegExp(
  String.raw`^(?:env\s+(?:${SHELL_ASSIGNMENT}\s+)*)?(?:${SHELL_ASSIGNMENT}\s+)*o2b\s+brain\s+(?:apply-evidence|feedback|note)(?:\s|$)`,
);

function splitShellCommandSegments(command: string): string[] {
  const segments: string[] = [];
  let current = "";
  let quote: "'" | '"' | null = null;

  for (let i = 0; i < command.length; i += 1) {
    const ch = command[i]!;
    if (quote) {
      current += ch;
      if (ch === "\\") {
        const next = command[i + 1];
        if (next !== undefined) {
          current += next;
          i += 1;
        }
        continue;
      }
      if (ch === quote) quote = null;
      continue;
    }

    if (ch === "\\") {
      // Outside-quotes backslash escapes the next character. Preserve
      // both so an escaped separator (`echo \; o2b brain note ...`)
      // does not split the segment.
      current += ch;
      const next = command[i + 1];
      if (next !== undefined) {
        current += next;
        i += 1;
      }
      continue;
    }
    if (ch === "'" || ch === '"') {
      quote = ch;
      current += ch;
      continue;
    }
    if (ch === ";" || ch === "&" || ch === "|") {
      segments.push(current);
      current = "";
      if (command[i + 1] === ch) i += 1;
      continue;
    }
    current += ch;
  }
  segments.push(current);
  return segments;
}

export function isArtifactToolName(name: string): boolean {
  return NATIVE_ARTIFACT_NAMES.has(name);
}

/**
 * True when `name` is one of the three brain-event tools (or a
 * runtime-decorated form thereof). §32 (v0.10.8) replaces the
 * v0.10.6 set: `event_log_append` is retired; `brain_note` is added.
 */
export function isBrainEventToolName(name: string): boolean {
  return BRAIN_EVENT_NAME_SUFFIX.test(name);
}

export interface TurnSummary {
  readonly hadArtifact: boolean;
  /**
   * True when any of `brain_feedback`, `brain_apply_evidence`, or
   * `brain_note` (MCP call or CLI invocation) landed in this turn.
   * §32 (v0.10.8): `event_log_append` no longer counts.
   */
  readonly hadBrainEvent: boolean;
}

export function summarizeTurn(
  toolCalls: readonly ToolCall[],
  bashCommandsThisTurn: readonly string[] = [],
): TurnSummary {
  let hadArtifact = false;
  let hadBrainEvent = false;
  for (const tc of toolCalls) {
    if (isArtifactToolName(tc.name)) hadArtifact = true;
    if (isBrainEventToolName(tc.name)) hadBrainEvent = true;
  }
  if (!hadBrainEvent) {
    for (const cmd of bashCommandsThisTurn) {
      if (
        splitShellCommandSegments(cmd).some((segment) =>
          BRAIN_EVENT_BASH_COMMAND_RE.test(segment.trim()),
        )
      ) {
        hadBrainEvent = true;
        break;
      }
    }
  }
  return { hadArtifact, hadBrainEvent };
}

// ---- Runtime detection (§4-tail) ---------------------------------------

/**
 * Which runtime is invoking the hook. `unknown` is the fail-safe and
 * renders byte-identical reminder text to the v0.10.4 baseline, so
 * a future runtime that breaks both signals never crashes the hook.
 */
export type HookRuntime = "claudecode" | "codex" | "grok" | "opencode" | "unknown";

const CLAUDE_TRANSCRIPT_NEEDLES = ["/.claude/projects/", "/.claude/sessions/"] as const;
const CODEX_TRANSCRIPT_NEEDLE = "/.codex/sessions/";

/**
 * Infer the runtime from a hook payload by shape. First-hit wins,
 * order matches the design doc:
 *
 *   1. Grok: camelCase payload shape (`hookEventName` / `workspaceRoot`) or a
 *      `GROK_*` hook env var. Grok ships no `transcript_path` and uses
 *      camelCase keys Claude/Codex never send, so this is unambiguous.
 *   2. `hook_host: "opencode"` - the explicit marker the opencode
 *      plugin's synthetic payloads carry (plugins/opencode/
 *      open-second-brain.ts states the same literal; the plugin is
 *      copied alone and cannot import this module). An honest marker,
 *      where a fabricated Claude Code `tool_use_id` would mislabel
 *      every audit row the lane writes - and it outranks the
 *      apply_patch shape, which an opencode patch payload shares.
 *   3. `transcript_path` substring (`/.claude/projects/`, `/.claude/sessions/`).
 *   4. `transcript_path` substring (`/.codex/sessions/`).
 *   5. Claude Code distinctive triple (`session_id` + `cwd` + `tool_use_id`).
 *   6. Claude Code Stop shape: `hook_event_name === "Stop"` with
 *      `stop_hook_active` and `last_assistant_message` but no `turn_id`
 *      (Codex adds `turn_id` to every Stop payload). Catches a Claude Code
 *      install whose transcripts live outside `~/.claude` (`CLAUDE_CONFIG_DIR`).
 *   7. Codex apply_patch shape (`tool_name === "apply_patch"` with
 *      a patch body in `tool_input.input`).
 *   8. `"unknown"`.
 *
 * `normalizeHookPayload` preserves grok's original camelCase keys, so this
 * works whether it runs before or after normalization. Malformed payloads
 * (`null`, primitives, missing fields, wrong types) resolve to `"unknown"`
 * without throwing — the hook never crashes on detection.
 */
export function detectHookRuntime(
  payload: unknown,
  env: Record<string, string | undefined> = process.env,
): HookRuntime {
  if (payload === null || typeof payload !== "object") return "unknown";
  const p = payload as Record<string, unknown>;

  if (typeof p["hookEventName"] === "string" || typeof p["workspaceRoot"] === "string") {
    return "grok";
  }
  if (env["GROK_HOOK_EVENT"] || env["GROK_SESSION_ID"] || env["GROK_WORKSPACE_ROOT"]) {
    return "grok";
  }

  // The opencode plugin's synthetic payloads state their host outright -
  // the most explicit signal there is, ahead of every shape guess. It
  // must outrank the apply_patch shape below: an opencode patch payload
  // carries the same `*** Begin Patch` body a Codex one does.
  if (p["hook_host"] === "opencode") return "opencode";

  const raw = p["transcript_path"];
  // On Windows the host sends a native path (`C:\Users\u\.claude\projects\…`);
  // the needles are written with `/`, so fold separators before matching.
  const tp = typeof raw === "string" ? raw.replaceAll("\\", "/") : raw;
  if (typeof tp === "string") {
    if (CLAUDE_TRANSCRIPT_NEEDLES.some((n) => tp.includes(n))) {
      return "claudecode";
    }
    if (tp.includes(CODEX_TRANSCRIPT_NEEDLE)) return "codex";
  }

  if (
    typeof p["session_id"] === "string" &&
    typeof p["cwd"] === "string" &&
    typeof p["tool_use_id"] === "string"
  ) {
    return "claudecode";
  }

  if (
    p["hook_event_name"] === "Stop" &&
    typeof p["stop_hook_active"] === "boolean" &&
    "last_assistant_message" in p &&
    !("turn_id" in p)
  ) {
    return "claudecode";
  }

  if (p["tool_name"] === "apply_patch") {
    const ti = p["tool_input"];
    if (ti !== null && typeof ti === "object") {
      const input = (ti as Record<string, unknown>)["input"];
      if (typeof input === "string" && input.includes("*** Begin Patch")) {
        return "codex";
      }
    }
  }

  return "unknown";
}