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
/**
* PreToolUse hook: opt-in backup of host Claude settings before agent
* file writes (t_f4555087).
*
* With `host_settings_backup` on (default OFF), a file-tool call
* (Write/Edit/MultiEdit/apply_patch) whose paths name a
* `.claude/settings.json` or `.claude/settings.local.json` at any level
* get their current content backed up - into the sibling folder beside
* the target (`<dir>/.o2b-backups/<name>/`), each backup a FILE named
* with the UTC stamp - and one audit receipt appended, before the call
* is allowed to proceed. A backup that cannot be taken DENIES the call:
* if the snapshot cannot be written, the write never proceeds.
*
* Codex `apply_patch` carries its targets inside the patch body, so
* every `*** (Update|Add|Delete) File:` header is parsed and each
* protected path is backed up (one patch, several backups). A settings
* file that is itself a symlink is protected through its lexical path,
* and the backup reads through the link. On first use the
* `.o2b-backups/` root gets a `*`-ignore marker, so a project-level
* backup is never left for the next `git add -A` to commit.
*
* Guarantees:
* - OPT-IN: the flag is checked FIRST; unset means an immediate
* no-op - no process ceiling, no payload read, zero output, so
* every tool call stays byte-identical to today.
* - FAIL-CLOSED (in-hook): the deny rides stdout as
* `hookSpecificOutput.permissionDecision: "deny"` naming the path -
* the only deny channel that survives the deliberately fail-soft
* `scripts/o2b-hook` dispatcher. A successful backup emits NOTHING:
* the call proceeds through the normal permission flow (an explicit
* allow here would pre-approve exactly the writes this hook exists
* to guard).
* - STDLIB-ONLY: this file imports no `src/core` behavior. The flag
* read, path predicate, backup executor, and receipt writer are
* restated here (their canonical twins live in
* `src/core/brain/pretool-host-backup.ts`, `src/core/trust.ts` and
* `src/core/reliability/audit.ts`), so a broken or absent core
* build cannot turn a failed backup into a failed hook load. The
* one sanctioned exception is the two directory-name constants
* from the leaf `src/core/brain/path-constants.ts` - names, not
* behavior - so the hook-audit root keeps its single spelling
* (`tests/hooks/audit-root.test.ts`), and the machine-state resolver
* the receipt asks where the audit lives once switched, imported
* lazily inside the receipt's own best-effort `try`. The receipt contract -
* actor, pid, before-hash, summary - is pinned against the trust
* conventions by tests, not by an import.
* - HARD FLOOR, stated honestly: the deny guarantee ends at this
* process. A missing bun, a missing hook script, or the fail-soft
* dispatcher swallowing a non-zero exit means no deny at all and
* the write proceeds unprotected. Documented, not hidden.
*
* Known gaps, recorded per the design:
* - Bash-class writes (redirections, `cp`, `tee`) are out of scope;
* the matcher is the file-tool family, and classifying shell
* commands is textual matching the repo avoids.
* - A temp-then-rename or symlink-swap write can land on a different
* path than the one that was canonicalized and backed up.
*/
import { createHash } from "node:crypto";
import {
closeSync,
existsSync,
fsyncSync,
mkdirSync,
openSync,
readFileSync,
realpathSync,
writeFileSync,
writeSync,
} from "node:fs";
import { homedir } from "node:os";
import { basename, dirname, isAbsolute, join, normalize, resolve } from "node:path";
import { DERIVED_STORE_DIR, HOOK_AUDIT_DIR } from "../src/core/brain/path-constants.ts";
import { detectHookRuntime } from "./lib/detect.ts";
import { asHookPayload, readHookInput } from "./lib/stdin.ts";
/** Exact file-tool family the hooks.json matcher registers. */
const WRITE_TOOL_NAMES: ReadonlySet<string> = new Set([
"Write",
"Edit",
"MultiEdit",
"apply_patch",
]);
/** Keys under which a tool's file-path argument may appear. */
const FILE_PATH_KEYS: ReadonlyArray<string> = ["file_path", "path"];
/** The settings basenames protected, and the managed dir they sit in. */
const PROTECTED_SETTINGS_NAMES: ReadonlySet<string> = new Set([
"settings.json",
"settings.local.json",
]);
const PROTECTED_DIR_NAME = ".claude";
/**
* Codex `apply_patch` carries its targets inside the patch body: every
* `*** Update File:` / `*** Add File:` / `*** Delete File:` header
* names one write path.
*/
const APPLY_PATCH_FILE_HEADER_RE = /\*\*\* (?:Update File|Add File|Delete File): ([^\n]+)/g;
/** Same-second backups ladder (`<stamp>-2`, ...); a bound, never an overwrite. */
const ALLOC_MAX_ATTEMPTS = 128;
/**
* The trust-conventions backup layout, restated (stdlib twin).
*/
const BACKUP_DIR_NAME = ".o2b-backups";
/**
* The git-ignore marker dropped into a `.o2b-backups/` root on first
* use (stdlib twin of ensureBackupRootIgnored): a project-level backup
* root sits inside someone's repository, and a settings.local.json
* copy can hold tokens - without it the next `git add -A` commits the
* backup.
*/
const BACKUP_IGNORE_FILE_TEXT = "*\n!.gitignore\n";
const PRE_TOOL_USE_EVENT = "PreToolUse";
function backupFolderStamp(d: Date): string {
const p = (n: number, w: number) => String(n).padStart(w, "0");
return (
`${p(d.getUTCFullYear(), 4)}-${p(d.getUTCMonth() + 1, 2)}-${p(d.getUTCDate(), 2)}` +
`-${p(d.getUTCHours(), 2)}${p(d.getUTCMinutes(), 2)}${p(d.getUTCSeconds(), 2)}`
);
}
function backupRootFor(target: string): string {
return join(join(dirname(target), BACKUP_DIR_NAME), basename(target));
}
// βββ Flag and vault, read stdlib-only ββββββββββββββββββββββββββββββββββ
/**
* The machine config path, matching the core default (XDG layout); the
* env override wins. A missing file means every key is unset.
*/
function configPath(): string {
const override = process.env["OPEN_SECOND_BRAIN_CONFIG"]?.trim();
if (override) return override;
const xdg = process.env["XDG_CONFIG_HOME"]?.trim();
return join(xdg || join(homedir(), ".config"), "open-second-brain", "config.yaml");
}
/**
* Cut an unquoted trailing `#...` comment: one scan tracking quote
* state, so a `#` INSIDE a quoted value (a vault path like
* `/data/brain#main`) stays whole. The stdlib twin of the canonical
* resolver's quote-aware YAML parsing.
*/
function stripUnquotedComment(value: string): string {
let quote: string | null = null;
for (let i = 0; i < value.length; i++) {
const ch = value[i]!;
if (quote !== null) {
if (ch === quote) quote = null;
} else if (ch === '"' || ch === "'") {
quote = ch;
} else if (ch === "#") {
return value.slice(0, i);
}
}
return value;
}
/** Value of a top-level `key:` in the config file, quotes stripped; null when unset. */
function configValue(key: string): string | null {
let text: string;
try {
text = readFileSync(configPath(), "utf8");
} catch {
return null;
}
const m = new RegExp(`^\\s*${key}\\s*:\\s*(.+?)\\s*$`, "m").exec(text);
if (m === null) return null;
const value = stripUnquotedComment(m[1]!)
.trim()
.replace(/^["']|["']$/g, "");
return value.length > 0 ? value : null;
}
/** Default-OFF flag read: env `true`/`1` wins, then the config key. */
function hostBackupEnabled(): boolean {
const env = process.env["OPEN_SECOND_BRAIN_HOST_SETTINGS_BACKUP"]?.trim();
if (env) return env === "true" || env === "1";
const key = configValue("host_settings_backup");
return key === "true" || key === "1";
}
/**
* The vault root the audit receipt lives under, resolved without core:
* the explicit env vars first, then the config `vault` key. Null skips
* the receipt - a missing vault never denies.
*/
function resolveVaultPath(): string | null {
const env = process.env["OPEN_SECOND_BRAIN_VAULT"]?.trim() || process.env["VAULT_DIR"]?.trim();
const raw = env || configValue("vault");
if (!raw) return null;
const expanded = raw === "~" || raw.startsWith("~/") ? join(homedir(), raw.slice(1)) : raw;
return isAbsolute(expanded) ? normalize(expanded) : null;
}
// βββ Path predicate (stdlib twin of decideHostBackup) βββββββββββββββββ
function canonicalize(raw: string, home: string, cwd: string): string {
const expanded = raw === "~" || raw.startsWith("~/") ? join(home, raw.slice(1)) : raw;
const absolute = isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
let prefix = normalize(absolute);
const tail: string[] = [];
for (;;) {
try {
prefix = realpathSync(prefix);
break;
} catch {
const parent = dirname(prefix);
if (parent === prefix) break;
tail.unshift(basename(prefix));
prefix = parent;
}
}
return normalize(join(prefix, ...tail));
}
function isProtectedSettingsPath(canonical: string): boolean {
if (basename(dirname(canonical)) !== PROTECTED_DIR_NAME) return false;
return PROTECTED_SETTINGS_NAMES.has(basename(canonical));
}
/**
* Every path one tool call would write, in payload order: the direct
* `file_path`/`path` argument when present, otherwise every
* `*** (Update|Add|Delete) File:` header of a Codex `apply_patch` body
* (one patch can touch several files) - the shape
* hooks/post-write-reminder.ts and hooks/lib/detect.ts already parse.
*/
function readCandidatePaths(toolInput: Record<string, unknown>): string[] {
const direct: string[] = [];
for (const key of FILE_PATH_KEYS) {
const value = toolInput[key];
if (typeof value === "string" && value.trim().length > 0) direct.push(value);
}
if (direct.length > 0) return direct;
const paths: string[] = [];
const input = toolInput["input"];
if (typeof input !== "string") return paths;
for (const m of input.matchAll(APPLY_PATCH_FILE_HEADER_RE)) {
const p = m[1]?.trim();
if (p) paths.push(p);
}
return paths;
}
function lexicallyHostPath(raw: string, home: string, cwd: string): string {
const expanded = raw === "~" || raw.startsWith("~/") ? join(home, raw.slice(1)) : raw;
const absolute = isAbsolute(expanded) ? expanded : resolve(cwd, expanded);
return normalize(absolute);
}
/**
* The protected targets of one tool call. The predicate tests BOTH the
* lexical path (tilde and cwd expanded) and the realpath: a settings
* file that is itself a symlink (stow-style dotfiles) canonicalizes
* its final component into an unprotected directory, so the realpath
* alone says not-protected for a file every operator would call
* `~/.claude/settings.json`. Either match protects; the lexical path
* wins as the backup target, because that is the path the tool call
* names and the place a backup belongs beside.
*/
function protectedTargets(toolName: string, toolInput: Record<string, unknown>): string[] {
if (!WRITE_TOOL_NAMES.has(toolName)) return [];
const targets: string[] = [];
for (const raw of readCandidatePaths(toolInput)) {
const lexical = lexicallyHostPath(raw, homedir(), process.cwd());
const canonical = canonicalize(raw, homedir(), process.cwd());
const target = isProtectedSettingsPath(lexical)
? lexical
: isProtectedSettingsPath(canonical)
? canonical
: null;
if (target !== null && !targets.includes(target)) targets.push(target);
}
return targets;
}
// βββ Fail-closed backup + receipt (stdlib twins) ββββββββββββββββββββββ
type BackupOutcome =
| { kind: "allow-no-source"; reason: string }
| { kind: "backed-up"; backupPath: string; beforeHash: string; bytes: number };
function executeBackup(target: string, now: Date): BackupOutcome {
// The twin's allow-no-source (executeHostBackup): a missing source is
// nothing to protect, so the write may CREATE the settings file -
// denying it here would make a fresh `.claude/settings.json`
// unreachable with the flag on.
if (!existsSync(target)) {
return { kind: "allow-no-source", reason: `${target} does not exist yet` };
}
let contents: string;
try {
contents = readFileSync(target, "utf8");
} catch (err) {
throw new Error(`cannot read ${target} for backup: ${(err as Error).message}`);
}
const beforeHash = `sha256:${createHash("sha256").update(contents).digest("hex")}`;
const root = backupRootFor(target);
const stamp = backupFolderStamp(now);
mkdirSync(root, { recursive: true });
// Git hygiene, best-effort - the ignore marker is not the guard, and
// a failed write never fails the backup (the ladder below still
// denies on failure).
try {
const marker = join(dirname(root), ".gitignore");
if (!existsSync(marker)) writeFileSync(marker, BACKUP_IGNORE_FILE_TEXT, { mode: 0o644 });
} catch {
// hygiene marker, not the guard
}
for (let attempt = 1; attempt <= ALLOC_MAX_ATTEMPTS; attempt++) {
const name = attempt === 1 ? stamp : `${stamp}-${attempt}`;
const candidate = join(root, name);
// Exclusive create (O_EXCL): a same-second second backup ladders
// its name; an exhausted ladder refuses rather than overwrites.
let fd: number;
try {
fd = openSync(candidate, "wx", 0o600);
} catch (err) {
if ((err as NodeJS.ErrnoException | null)?.code === "EEXIST") continue;
throw new Error(`cannot write backup for ${target}: ${(err as Error).message}`);
}
try {
// Full-write loop (the core twin's durability, fs-atomic
// withTempFile): writeSync may take fewer bytes than asked, and a
// truncated backup reported as success would let the guarded
// write proceed on a corrupt snapshot. A short write that never
// throws keeps looping; only a full byte count plus the fsyncs
// below count as taken.
const buf = Buffer.from(contents, "utf8");
let written = 0;
while (written < buf.byteLength) {
written += writeSync(fd, buf, written, buf.byteLength - written);
}
fsyncSync(fd);
// Best-effort fsync of the parent dir, so the new backup entry is
// durable too (no portable dir fsync; failures on platforms
// without the O_RDONLY-dir trick are not fatal).
try {
const dfd = openSync(root, "r");
try {
fsyncSync(dfd);
} finally {
closeSync(dfd);
}
} catch {
// durability optimization, not the guard
}
} finally {
closeSync(fd);
}
return {
kind: "backed-up",
backupPath: candidate,
beforeHash,
bytes: contents.length,
};
}
throw new Error(
`host settings backup allocation exhausted for ${target} ` +
`(${ALLOC_MAX_ATTEMPTS} candidates taken for ${stamp}); refusing to overwrite`,
);
}
function isoWeekLabel(d: Date): string {
const date = new Date(Date.UTC(d.getUTCFullYear(), d.getUTCMonth(), d.getUTCDate()));
const dayNumber = date.getUTCDay() || 7;
date.setUTCDate(date.getUTCDate() + 4 - dayNumber);
const yearStart = new Date(Date.UTC(date.getUTCFullYear(), 0, 1));
const week = Math.ceil(((date.getTime() - yearStart.getTime()) / 86_400_000 + 1) / 7);
return `${date.getUTCFullYear()}-W${String(week).padStart(2, "0")}`;
}
/**
* The audit receipt, restated against the trust conventions (actor,
* pid, before-hash, summary plus the backup path). Best-effort: a
* failed append must not turn a completed backup into a deny.
*/
async function appendReceipt(
vault: string | null,
target: string,
backup: { backupPath: string; beforeHash: string; bytes: number },
actor: string,
now: Date,
): Promise<void> {
if (vault === null) return;
try {
// Machine state: device-local once switched (`machineStatePath`).
// Imported here, inside the best-effort receipt, never at load: a
// broken core build then costs the receipt, never the backup or the
// deny (STDLIB-ONLY above), and the flag-off path loads nothing.
const { machineStatePath } = await import("../src/core/state/machine-state.ts");
const dir = machineStatePath(vault, DERIVED_STORE_DIR, HOOK_AUDIT_DIR);
mkdirSync(dir, { recursive: true });
const record = {
timestamp: now.toISOString(),
actor,
action: "host-settings-backup",
target,
ok: true,
details: {
pid: process.pid,
before_hash: backup.beforeHash,
summary: `backed up ${basename(target)} (${backup.bytes} bytes) before an agent file write`,
backup: backup.backupPath,
},
};
const path = join(dir, `${isoWeekLabel(now)}.jsonl`);
let fd: number;
try {
fd = openSync(path, "wx", 0o600);
} catch (err) {
if ((err as NodeJS.ErrnoException | null)?.code !== "EEXIST") throw err;
fd = openSync(path, "a");
}
try {
writeSync(fd, JSON.stringify(record) + "\n");
} finally {
closeSync(fd);
}
} catch {
// best-effort: the receipt is evidence, not the guard
}
}
// βββ Wrapper βββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
function emitPermission(permissionDecision: "deny" | "allow", reason: string): void {
const out = {
hookSpecificOutput: {
hookEventName: PRE_TOOL_USE_EVENT,
permissionDecision,
permissionDecisionReason: reason,
},
};
process.stdout.write(JSON.stringify(out) + "\n");
}
async function main(): Promise<void> {
// Fast opt-out FIRST: default OFF means an immediate no-op - no
// process ceiling, no payload read, zero output.
if (!hostBackupEnabled()) return;
// Armed only after the flag check, and imported only here, so the off
// path (and a broken plumbing helper) stays a byte-identical no-op.
const { armProcessCeiling, resolveHookCeilingMs } = await import("./lib/process-ceiling.ts");
const disarm = armProcessCeiling({ ceilingMs: resolveHookCeilingMs() });
try {
let raw: unknown;
try {
raw = await readHookInput();
} catch {
return; // unreadable payload -> nothing to guard, fail open
}
const payload = asHookPayload(raw);
const toolName = typeof payload.tool_name === "string" ? payload.tool_name : "";
const toolInput =
payload.tool_input !== null && typeof payload.tool_input === "object"
? (payload.tool_input as Record<string, unknown>)
: {};
const targets = protectedTargets(toolName, toolInput);
if (targets.length === 0) return; // not a protected settings file: silent allow
const now = new Date();
for (const target of targets) {
try {
const backup = executeBackup(target, now);
if (backup.kind === "allow-no-source") continue; // nothing to protect: silent allow
// Never rejects: every failure inside it is swallowed.
await appendReceipt(
resolveVaultPath(),
target,
backup,
`hook:${detectHookRuntime(raw)}`,
now,
);
// Silent success: the call proceeds through the normal permission
// flow; the backup already happened. An explicit allow here would
// pre-approve the very write this hook guards.
} catch (err) {
emitPermission(
"deny",
`host settings backup failed for ${target}; write refused: ${(err as Error).message}`,
);
return;
}
}
} finally {
disarm();
}
}
main().catch(() => {
// Never crash the runtime; a hook misbehaviour must not break the tool
// call beyond the deny this hook can still have emitted.
});