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
/**
* Lock the resilient shape of every hook command in hooks/hooks.json.
*
* Each command must resolve the wrapper via $CLAUDE_PLUGIN_ROOT (Claude Code,
* current version) with a PATH fallback (Codex / stable dir) and must end with
* `exit 0` so a hook can never block the agent. The bare `o2b-hook <name>`
* form is forbidden because it relies solely on a PATH symlink that goes stale
* across plugin updates.
*/
import { describe, expect, setDefaultTimeout, test } from "bun:test";
import { spawnSync } from "node:child_process";
import { existsSync, readFileSync } from "node:fs";
import { dirname, join, resolve } from "node:path";
import { fileURLToPath } from "node:url";
import { CLI_SPAWN_BUDGET_MS } from "../helpers/cli-timeout.ts";
// Tests here spawn processes; see tests/helpers/cli-timeout.ts.
setDefaultTimeout(CLI_SPAWN_BUDGET_MS);
const REPO = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
const HOOKS_JSON = join(REPO, "hooks", "hooks.json");
interface HookEntry {
type: string;
command: string;
statusMessage?: string;
}
function allCommands(): string[] {
const parsed = JSON.parse(readFileSync(HOOKS_JSON, "utf8")) as {
hooks: Record<string, Array<{ hooks: HookEntry[] }>>;
};
const cmds: string[] = [];
for (const groups of Object.values(parsed.hooks)) {
for (const group of groups) {
for (const h of group.hooks) {
if (h.type === "command") cmds.push(h.command);
}
}
}
return cmds;
}
describe("hooks.json command shape", () => {
const cmds = allCommands();
test("is valid JSON with at least one command", () => {
expect(cmds.length).toBeGreaterThan(0);
});
test("every command is version-current, has a PATH fallback, and never blocks", () => {
for (const cmd of cmds) {
expect(cmd).toContain("$CLAUDE_PLUGIN_ROOT");
expect(cmd).toContain("/scripts/o2b-hook");
expect(cmd).toContain("command -v o2b-hook");
expect(cmd.trimEnd().endsWith("exit 0")).toBe(true);
// Must NOT be the bare PATH-only form.
expect(/^o2b-hook\s/.test(cmd.trim())).toBe(false);
}
});
test("SessionStart matcher covers compact - the supported post-compaction re-injection path", () => {
const parsed = JSON.parse(readFileSync(HOOKS_JSON, "utf8")) as {
hooks: Record<string, Array<{ matcher?: string }>>;
};
const sessionStart = parsed.hooks["SessionStart"] ?? [];
expect(sessionStart.length).toBeGreaterThan(0);
for (const group of sessionStart) {
expect(group.matcher).toBe("startup|resume|clear|compact");
}
});
test("reground-deliver rides the PostToolUse * and UserPromptSubmit * groups", () => {
const parsed = JSON.parse(readFileSync(HOOKS_JSON, "utf8")) as {
hooks: Record<string, Array<{ matcher?: string; hooks: HookEntry[] }>>;
};
for (const event of ["PostToolUse", "UserPromptSubmit"]) {
const star = (parsed.hooks[event] ?? []).filter((group) => group.matcher === "*");
expect(`${event}: ${star.length}`).toBe(`${event}: 1`);
const last = star[0]!.hooks.at(-1)!;
expect(last.command.trimEnd()).toEndWith(
"command -v o2b-hook >/dev/null 2>&1 && exec o2b-hook reground-deliver; exit 0",
);
}
});
test("the PostToolUse reground-deliver entry shows no status line on every tool call", () => {
const parsed = JSON.parse(readFileSync(HOOKS_JSON, "utf8")) as {
hooks: Record<string, Array<{ matcher?: string; hooks: HookEntry[] }>>;
};
const carriers = (parsed.hooks["PostToolUse"] ?? [])
.flatMap((group) => group.hooks)
.filter((h) => h.command.includes("o2b-hook reground-deliver"));
expect(carriers.length).toBe(1);
expect(carriers[0]!.statusMessage).toBeUndefined();
});
// Runs the command through `sh` with a POSIX PATH (/usr/bin:/bin); native
// Windows has neither, so the fixture cannot be built there.
test.skipIf(process.platform === "win32")(
"a command never blocks when nothing resolves (exit 0)",
() => {
const cmd = cmds[0]!;
const env = { ...process.env } as Record<string, string | undefined>;
delete env["CLAUDE_PLUGIN_ROOT"];
delete env["OSB_PLUGIN_ROOT"];
// Minimal PATH: sh + coreutils resolve, but the `o2b-hook` fallback
// (installed under ~/.local/bin) does not.
env["PATH"] = "/usr/bin:/bin";
const r = spawnSync("sh", ["-c", cmd], { env, encoding: "utf8" });
expect(r.status).toBe(0);
},
);
});
describe("hooks.json Stop hygiene-digest entry", () => {
const stopGroups =
(
JSON.parse(readFileSync(HOOKS_JSON, "utf8")) as {
hooks: Record<
string,
Array<{ matcher?: string; hooks: Array<HookEntry & { timeout?: number }> }>
>;
}
).hooks["Stop"] ?? [];
test("exactly one Stop * group carries exactly one hygiene-digest entry, last in the group", () => {
const stars = stopGroups.filter((group) => group.matcher === "*");
expect(stars.length).toBe(1);
const hooks = stars[0]!.hooks;
const guardrail = hooks.findIndex((h) => h.command.includes("o2b-hook stop-log-guardrail"));
expect(guardrail).toBeGreaterThanOrEqual(0);
const digestIndices = hooks
.map((h, i) => (h.command.includes("o2b-hook hygiene-digest") ? i : -1))
.filter((i) => i >= 0);
expect(digestIndices).toEqual([hooks.length - 1]);
});
test("the Stop * group carries exactly one answer-quote-check entry, after stop-log-guardrail", () => {
const stars = stopGroups.filter((group) => group.matcher === "*");
expect(stars.length).toBe(1);
const hooks = stars[0]!.hooks;
const guardrail = hooks.findIndex((h) => h.command.includes("o2b-hook stop-log-guardrail"));
const digest = hooks.findIndex((h) => h.command.includes("o2b-hook hygiene-digest"));
const quoteChecks = hooks
.map((h, i) => (h.command.includes("o2b-hook answer-quote-check") ? i : -1))
.filter((i) => i >= 0);
expect(quoteChecks).toEqual([guardrail + 1]);
expect(quoteChecks[0]).toBeLessThan(digest);
// The annotation can never block the agent: same resilient shape as
// every sibling, and the dispatch target resolves to an existing hook.
const entry = hooks[quoteChecks[0]!]!;
expect(entry.timeout).toBe(10);
expect(entry.statusMessage).toBeDefined();
expect(entry.type).toBe("command");
const tail = entry.command.trimEnd();
expect(tail.endsWith("exit 0")).toBe(true);
const match = /exec o2b-hook ([a-z0-9-]+); exit 0$/.exec(tail);
expect(match).not.toBeNull();
expect(existsSync(join(REPO, "hooks", match![1]! + ".ts"))).toBe(true);
});
test("the hygiene-digest dispatch target resolves to an existing hook file with the sibling timeout and fail-soft shape", () => {
const hooks = stopGroups.filter((group) => group.matcher === "*")[0]!.hooks;
const entry = hooks.find((h) => h.command.includes("o2b-hook hygiene-digest"))!;
expect(entry.timeout).toBe(10);
expect(entry.statusMessage).toBeDefined();
expect(entry.type).toBe("command");
const tail = entry.command.trimEnd();
expect(tail.endsWith("exit 0")).toBe(true);
const match = /exec o2b-hook ([a-z0-9-]+); exit 0$/.exec(tail);
expect(match).not.toBeNull();
expect(existsSync(join(REPO, "hooks", match![1]! + ".ts"))).toBe(true);
});
});
describe("hooks.json subagent-inject entry", () => {
test("the PostToolUse write group carries the carrier after post-write-reminder, shaped like its siblings", () => {
const parsed = JSON.parse(readFileSync(HOOKS_JSON, "utf8")) as {
hooks: Record<
string,
Array<{ matcher?: string; hooks: Array<HookEntry & { timeout?: number }> }>
>;
};
const group = (parsed.hooks["PostToolUse"] ?? []).find(
(g) => g.matcher === "Write|Edit|MultiEdit|apply_patch",
);
expect(group).toBeDefined();
const hooks = group!.hooks;
const carriers = hooks.filter((h) => h.command.includes("o2b-hook subagent-inject"));
expect(carriers.length).toBe(1);
const carrier = carriers[0]!;
// Registered inside the write-shaped group, right after its
// post-write-reminder sibling: both fire on the same tool calls.
expect(hooks.at(-1)).toBe(carrier);
expect(hooks[hooks.indexOf(carrier) - 1]!.command).toContain("o2b-hook post-write-reminder");
expect(carrier.type).toBe("command");
expect(carrier.timeout).toBe(10);
expect(carrier.statusMessage).toBe("OSB: delivering context to a subagent");
// Fail-soft shape identical to its sibling: same wrapper, same PATH
// fallback, same never-blocks tail, only the dispatch name differs.
// Both occurrences of the name (plugin-root branch and fallback) must
// map, so the swap is a replaceAll.
const sibling = hooks.find((h) => h.command.includes("o2b-hook post-write-reminder"))!;
expect(carrier.command).toBe(
sibling.command.replaceAll("post-write-reminder", "subagent-inject"),
);
// The dispatch target resolves to an existing hook file, so the
// registered name can never silently no-op.
expect(existsSync(join(REPO, "hooks", "subagent-inject.ts"))).toBe(true);
});
test("SubagentStart registers the same carrier as the primary channel", () => {
const parsed = JSON.parse(readFileSync(HOOKS_JSON, "utf8")) as {
hooks: Record<
string,
Array<{ matcher?: string; hooks: Array<HookEntry & { timeout?: number }> }>
>;
};
// Exactly one group over every sub-agent, carrying exactly one
// subagent-inject entry - the SubagentStart event fires when the Task
// tool spawns the sub-agent, before its first prompt.
const groups = parsed.hooks["SubagentStart"] ?? [];
expect(groups.length).toBe(1);
expect(groups[0]!.matcher).toBe("*");
const carriers = groups[0]!.hooks.filter((h) => h.command.includes("o2b-hook subagent-inject"));
expect(carriers.length).toBe(1);
expect(groups[0]!.hooks.length).toBe(1);
// The same fail-soft command, timeout and status shape as the
// PostToolUse fallback entry: one hook script, two registrations.
const postToolUseCarrier = (parsed.hooks["PostToolUse"] ?? [])
.flatMap((group) => group.hooks)
.find((h) => h.command.includes("o2b-hook subagent-inject"))!;
expect(carriers[0]!.command).toBe(postToolUseCarrier.command);
expect(carriers[0]!.timeout).toBe(postToolUseCarrier.timeout);
expect(carriers[0]!.statusMessage).toBe(postToolUseCarrier.statusMessage);
expect(carriers[0]!.type).toBe("command");
});
});
describe("hooks.json SessionStart backlog-nudge entry", () => {
const sessionStartGroups =
(
JSON.parse(readFileSync(HOOKS_JSON, "utf8")) as {
hooks: Record<
string,
Array<{ matcher?: string; hooks: Array<HookEntry & { timeout?: number }> }>
>;
}
).hooks["SessionStart"] ?? [];
test("the single SessionStart group carries exactly one backlog-nudge entry, after gap-agenda", () => {
expect(sessionStartGroups.length).toBe(1);
const hooks = sessionStartGroups[0]!.hooks;
const agenda = hooks.findIndex((h) => h.command.includes("o2b-hook gap-agenda"));
expect(agenda).toBeGreaterThanOrEqual(0);
const nudgeIndices = hooks
.map((h, i) => (h.command.includes("o2b-hook backlog-nudge") ? i : -1))
.filter((i) => i >= 0);
expect(nudgeIndices).toEqual([agenda + 1]);
});
test("the single SessionStart group carries exactly one log-catchup entry, after backlog-nudge", () => {
expect(sessionStartGroups.length).toBe(1);
const hooks = sessionStartGroups[0]!.hooks;
const nudge = hooks.findIndex((h) => h.command.includes("o2b-hook backlog-nudge"));
expect(nudge).toBeGreaterThanOrEqual(0);
const catchupIndices = hooks
.map((h, i) => (h.command.includes("o2b-hook log-catchup") ? i : -1))
.filter((i) => i >= 0);
expect(catchupIndices).toEqual([nudge + 1]);
// Session-capture stays last: the lifecycle event records the start
// of the session, after every injection lane has had its turn.
const capture = hooks.findIndex((h) => h.command.includes("o2b-hook session-capture"));
expect(capture).toBe(hooks.length - 1);
expect(capture).toBeGreaterThan(catchupIndices[0]!);
});
test("the log-catchup entry declares the sibling timeout and the opt-in status line", () => {
const hooks = sessionStartGroups[0]!.hooks;
const entry = hooks.find((h) => h.command.includes("o2b-hook log-catchup"))!;
expect(entry.type).toBe("command");
expect(entry.timeout).toBe(10);
expect(entry.statusMessage).toBe("OSB: injecting cross-agent log catch-up (opt-in)");
// The dispatch target resolves to an existing hook file, so the
// registered name can never silently no-op.
expect(existsSync(join(REPO, "hooks", "log-catchup.ts"))).toBe(true);
// Same resilient shape as every sibling: plugin-root wrapper, PATH
// fallback, never-blocks tail.
const sibling = hooks.find((h) => h.command.includes("o2b-hook backlog-nudge"))!;
expect(entry.command).toBe(sibling.command.replaceAll("backlog-nudge", "log-catchup"));
expect(entry.command.trimEnd().endsWith("exit 0")).toBe(true);
});
test("the backlog-nudge entry declares the sibling timeout and the opt-in status line", () => {
const hooks = sessionStartGroups[0]!.hooks;
const entry = hooks.find((h) => h.command.includes("o2b-hook backlog-nudge"))!;
expect(entry.type).toBe("command");
expect(entry.timeout).toBe(10);
expect(entry.statusMessage).toBe("OSB: injecting undistilled backlog count (opt-in)");
// The dispatch target resolves to an existing hook file, so the
// registered name can never silently no-op.
expect(existsSync(join(REPO, "hooks", "backlog-nudge.ts"))).toBe(true);
});
});
describe("hooks.json PreToolUse host-settings backup entry (t_f4555087)", () => {
const groups =
(
JSON.parse(readFileSync(HOOKS_JSON, "utf8")) as {
hooks: Record<
string,
Array<{ matcher?: string; hooks: Array<HookEntry & { timeout?: number }> }>
>;
}
).hooks["PreToolUse"] ?? [];
test("a write-family matcher group carries exactly one pretool-host-backup entry", () => {
const group = groups.find((g) => g.matcher === "Write|Edit|MultiEdit|apply_patch");
expect(group).toBeDefined();
const carriers = (group?.hooks ?? []).filter((h) =>
h.command.includes("o2b-hook pretool-host-backup"),
);
expect(carriers.length).toBe(1);
const entry = carriers[0]!;
expect(entry.type).toBe("command");
expect(entry.timeout).toBe(10);
expect(entry.statusMessage).toBe("OSB: backing up host settings before writes (opt-in)");
expect(entry.command.trimEnd()).toEndWith(
"command -v o2b-hook >/dev/null 2>&1 && exec o2b-hook pretool-host-backup; exit 0",
);
});
test("the orientation group keeps its * matcher and the backup group sits beside it", () => {
const orient = groups.filter(
(g) => g.matcher === "*" && g.hooks.some((h) => h.command.includes("pretool-orient")),
);
expect(orient.length).toBe(1);
// Two PreToolUse groups now: the orient gate and the backup gate.
expect(groups.length).toBe(2);
});
test("the dispatch target resolves to an existing hook file", () => {
expect(existsSync(join(REPO, "hooks", "pretool-host-backup.ts"))).toBe(true);
});
});