Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* skill-resolver-hook.ts — the skill-resolver lane's hook wiring
* (`GBRAIN_HOOK_LANE=skill-resolver`, runtime in
* src/core/skills/resolver/hook-lane.ts), written by
* `gbrain setup <claude-code|codex> --skill-loading resolve`
* (skill-resolver-setup.ts) and removed by `--skill-loading off` and
* `setup --remove`.
*
* - Claude Code: its own entries in the user settings file, marked
* `skill-resolver-v1`: UserPromptSubmit (`hook user-prompt`) and
* SessionStart (`hook session-start`, which only resets a session's
* dedupe state after a compaction).
* - Codex: its own UserPromptSubmit group in CODEX_HOME/hooks.json
* (`hook user-prompt --harness codex`) and its own SessionStart group
* (`hook session-start --harness codex`, the same compaction reset:
* Codex sends SessionStart with source "compact" after it compacts),
* each trusted by its hash in config.toml beside it, like the turn-rule
* lane.
* - Hermes: its own `pre_llm_call` entry (`hook user-prompt --harness
* hermes`) in gbrain's marked `hooks:` block in $HERMES_HOME/config.yaml,
* beside the turn rule's (hermes-turn-hook.ts), approved in Hermes's
* shell-hooks-allowlist.json. Hermes splits the command like shlex with no
* shell and needs its first word to be a file, so it starts with
* /usr/bin/env. Hermes has no SessionStart: the lane resets a session's
* dedupe state itself when the history shrinks (in-place compaction).
*
* All three run gbrain through the existing hook launcher (hook-launcher.ts); this
* module writes nothing else into the launcher's directory. Ownership: the
* marker, else the lane token in the command (Claude Code), the lane token
* (Codex). Nothing else in either file is touched.
*/
import { mkdirSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { ownedEntryFingerprint } from '../bootstrap/adopted-connections.ts';
import { codexHookCensus, codexHookGroupRuns, codexSetupHookGroup, codexSetupTrustEntry, writeCodexSetupHooks, type CodexHookGroup } from '../bootstrap/codex-hooks.ts';
import { appendCodexTomlTable, readCodexTomlTable, removeCodexTomlTable } from '../bootstrap/codex-toml.ts';
import { buildClaudeHookCommand, hookEntryHash, removeClaudeHooksAt, writeClaudeHooksAt } from '../bootstrap/hooks.ts';
import { shellQuote } from '../shell-quote.ts';
import { CLAUDE_HOOK_DEFAULT_TIMEOUT_SECS, claudeUserSettingsPath, codexConfigPath, codexHooksPath, type ClaudeHookEvent } from '../bootstrap/host-specs.ts';
import { brainFirstTarget } from './brain-first.ts';
import { inspectHermesResolverHook, removeHermesHook, syncHermesHook } from './hermes-turn-hook.ts';
import { readJsonObjectSafe } from './skill-resolver-config.ts';
import { ensureHookLauncher, hookLauncherPath, hookLauncherState } from './hook-launcher.ts';
import { isSkillResolverCommand, isSkillResolverEntry, SKILL_RESOLVER_LANE, SKILL_RESOLVER_MARKER } from './skill-resolver-lane.ts';
export type ResolverHarness = 'claude-code' | 'codex' | 'hermes';
const CLAUDE_EVENTS: ClaudeHookEvent[] = ['UserPromptSubmit', 'SessionStart'];
const CODEX_EVENTS = ['UserPromptSubmit', 'SessionStart'] as const;
type CodexEvent = (typeof CODEX_EVENTS)[number];
const CODEX_TIMEOUT_SECS = 15;
export interface ResolverHookPaths { claudeSettings?: string; codexHooks?: string; codexConfig?: string; hookLauncher?: string; hermesHome?: string }
export interface ResolverHookOutcome { action: 'write' | 'keep' | 'remove' | 'skip' | 'refuse'; path: string; detail: string }
const claudePath = (p: ResolverHookPaths) => p.claudeSettings ?? claudeUserSettingsPath();
const codexPaths = (p: ResolverHookPaths) => ({ hooks: p.codexHooks ?? codexHooksPath(), config: p.codexConfig ?? codexConfigPath() });
/** $HERMES_HOME (else ~/.hermes): where SOUL.md, config.yaml and skills/ live. */
export const hermesHomeDir = (): string => dirname((brainFirstTarget('hermes') as { path: string }).path);
const hermesHome = (p: ResolverHookPaths) => p.hermesHome ?? hermesHomeDir();
const laneEnv = (home: string | undefined) => ({ ...(home ? { GBRAIN_HOME: home } : {}), GBRAIN_HOOK_LANE: SKILL_RESOLVER_LANE });
/** Every entry of this lane in a Claude Code settings file, by event. */
function claudeOurs(path: string): Array<{ event: string; entry: Record<string, unknown> }> {
const hooks = readJsonObjectSafe(path)?.hooks;
if (!hooks || typeof hooks !== 'object' || Array.isArray(hooks)) return [];
return Object.entries(hooks as Record<string, unknown>).flatMap(([event, groups]) => (Array.isArray(groups) ? groups : [])
.flatMap((g) => (Array.isArray((g as { hooks?: unknown })?.hooks) ? (g as { hooks: unknown[] }).hooks : []))
.filter(isSkillResolverEntry).map((entry) => ({ event, entry: entry as Record<string, unknown> })));
}
function codexOurs(p: { hooks: string }) {
return codexHookCensus(p.hooks).filter((g) => (CODEX_EVENTS as readonly string[]).includes(g.event) && g.commands.some(isSkillResolverCommand)) as Array<ReturnType<typeof codexHookCensus>[number] & { event: CodexEvent }>;
}
export function codexResolverGroup(bin: string, home: string | undefined, launcher: string, event: CodexEvent = 'UserPromptSubmit'): CodexHookGroup {
return codexSetupHookGroup(bin, event, home ? { GBRAIN_HOME: home } : {}, SKILL_RESOLVER_LANE, launcher);
}
const codexTrusted = (p: { hooks: string; config: string }, g: { event: CodexEvent; index: number }) => codexHookGroupRuns(p.hooks, p.config, g);
/** The Hermes entry's command: no shell, so the environment goes through /usr/bin/env and every word is shlex-quoted. */
export function hermesResolverCommand(bin: string, home: string | undefined, launcher: string): string {
return ['/usr/bin/env', `GBRAIN_HOOK_LANE=${SKILL_RESOLVER_LANE}`, ...(home ? [`GBRAIN_HOME=${home}`] : []), launcher, bin, 'hook', 'user-prompt', '--harness', 'hermes'].map((w) => (/^[\w.:/@=-]+$/.test(w) ? w : shellQuote(w))).join(' ');
}
/** The commands this install's lane runs (what the hook entries would hold). */
export function skillResolverCommands(harness: ResolverHarness, bin: string, home: string | undefined, launcher: string): string[] {
if (harness === 'hermes') return [hermesResolverCommand(bin, home, launcher)];
if (harness === 'codex') return CODEX_EVENTS.flatMap((e) => codexResolverGroup(bin, home, launcher, e).hooks.map((h) => h.command));
return CLAUDE_EVENTS.map((e) => buildClaudeHookCommand(bin, e, laneEnv(home), launcher));
}
/**
* Whether this lane's hook is present: absent, wired (and, on Codex,
* trusted), untrusted, or outdated (the UserPromptSubmit hook without the
* SessionStart compaction reset, an install from before it; setup adds it).
*/
export type ResolverHookState = 'absent' | 'wired' | 'untrusted' | 'outdated';
export function inspectSkillResolverHook(harness: ResolverHarness, paths: ResolverHookPaths = {}): { state: ResolverHookState; path: string; commands: string[] } {
try {
if (harness === 'hermes') {
const h = inspectHermesResolverHook(hermesHome(paths));
return { state: h.state === 'absent' ? 'absent' : h.state === 'approved' ? 'wired' : 'untrusted', path: h.path, commands: h.command ? [h.command] : [] };
}
if (harness === 'codex') {
const p = codexPaths(paths);
const ours = codexOurs(p);
const commands = ours.flatMap((g) => g.commands);
if (!ours.some((g) => g.event === 'UserPromptSubmit')) return { state: 'absent', path: p.hooks, commands: [] };
if (!ours.some((g) => g.event === 'SessionStart')) return { state: 'outdated', path: p.hooks, commands };
return { state: ours.every((g) => codexTrusted(p, g)) ? 'wired' : 'untrusted', path: p.hooks, commands };
}
const path = claudePath(paths);
const ours = claudeOurs(path);
const has = (event: string) => ours.some((o) => o.event === event);
return { state: !has('UserPromptSubmit') ? 'absent' : has('SessionStart') ? 'wired' : 'outdated', path, commands: ours.map((o) => String(o.entry.command)) };
} catch {
return { state: 'absent', path: harness === 'hermes' ? join(hermesHome(paths), 'config.yaml') : harness === 'codex' ? codexPaths(paths).hooks : claudePath(paths), commands: [] };
}
}
/** Install or refresh the lane's hook. Throws on a file it cannot write safely. */
export function syncSkillResolverHook(opts: { harness: ResolverHarness; gbrainBin: string; gbrainHome?: string; paths?: ResolverHookPaths; dryRun?: boolean }): ResolverHookOutcome {
const paths = opts.paths ?? {};
const launcher = paths.hookLauncher ?? hookLauncherPath();
const launcherFresh = hookLauncherState(launcher).state === 'current';
if (!opts.dryRun) ensureHookLauncher(launcher);
const out = opts.harness === 'hermes' ? syncHermes(opts.gbrainBin, opts.gbrainHome, launcher, hermesHome(paths), !!opts.dryRun)
: opts.harness === 'codex' ? syncCodex(opts.gbrainBin, opts.gbrainHome, launcher, codexPaths(paths), !!opts.dryRun)
: syncClaude(opts.gbrainBin, opts.gbrainHome, launcher, claudePath(paths), !!opts.dryRun);
return out.action === 'keep' && !launcherFresh ? { ...out, action: 'write', detail: `${out.detail}; hook launcher ${launcher}` } : out;
}
function syncClaude(bin: string, home: string | undefined, launcher: string, path: string, dryRun: boolean): ResolverHookOutcome {
const want = CLAUDE_EVENTS.map((e) => hookEntryHash({ type: 'command', command: buildClaudeHookCommand(bin, e, laneEnv(home), launcher), timeout: CLAUDE_HOOK_DEFAULT_TIMEOUT_SECS[e] })!);
const ours = claudeOurs(path);
const detail = `skill-resolver lane hooks (UserPromptSubmit, SessionStart) in ${path}`;
const have = ours.map((o) => hookEntryHash(o.entry));
if (have.length === want.length && want.every((h) => have.includes(h))) return { action: 'keep', path, detail };
if (dryRun) return { action: 'write', path, detail };
mkdirSync(dirname(path), { recursive: true });
writeClaudeHooksAt(path, { gbrainBin: bin, hookLauncher: launcher, env: { ...laneEnv(home), GBRAIN_SEAT: '' }, events: CLAUDE_EVENTS, marker: SKILL_RESOLVER_MARKER,
ownedEntryHashes: new Set([...want, ...have.filter((h): h is string => !!h)]), freshMode: 0o600 });
return { action: 'write', path, detail };
}
function syncHermes(bin: string, home: string | undefined, launcher: string, hermes: string, dryRun: boolean): ResolverHookOutcome {
const o = syncHermesHook({ hermesHome: hermes, lane: 'skill-resolver', command: hermesResolverCommand(bin, home, launcher), dryRun });
if (o.action === 'print') return { action: 'refuse', path: o.path, detail: `${o.detail}:\n${o.snippet}` };
return { action: o.action === 'keep' ? 'keep' : 'write', path: o.path, detail: o.detail };
}
const trustPath = (key: string) => ['hooks', 'state', key];
/** Drop the trust entries of our groups, each only while it still trusts one of our commands. */
function dropOurTrust(config: string, hooks: string, ours: ReturnType<typeof codexOurs>): void {
const commands = ours.flatMap((g) => g.commands);
for (const g of ours) {
const entries = commands.map((command) => codexSetupTrustEntry(hooks, g.event, g.index, { hooks: [{ type: 'command', command, timeout: CODEX_TIMEOUT_SECS }] }));
const table = readCodexTomlTable(config, trustPath(entries[0]!.key)) as { trusted_hash?: unknown } | undefined;
if (table && entries.some((t) => t.trusted_hash === table.trusted_hash)) removeCodexTomlTable(config, trustPath(entries[0]!.key));
}
}
function syncCodex(bin: string, home: string | undefined, launcher: string, p: { hooks: string; config: string }, dryRun: boolean): ResolverHookOutcome {
const groups = Object.fromEntries(CODEX_EVENTS.map((e) => [e, codexResolverGroup(bin, home, launcher, e)])) as Record<CodexEvent, CodexHookGroup>;
const ours = codexOurs(p);
const detail = `skill-resolver lane hooks (UserPromptSubmit, SessionStart) in ${p.hooks}, trusted in ${p.config}`;
const current = ours.length === CODEX_EVENTS.length && CODEX_EVENTS.every((e) => ours.some((g) => g.event === e && g.hash === ownedEntryFingerprint(groups[e]) && codexTrusted(p, g)));
if (current) return { action: 'keep', path: p.hooks, detail };
if (dryRun) return { action: 'write', path: p.hooks, detail };
mkdirSync(dirname(p.hooks), { recursive: true, mode: 0o700 });
dropOurTrust(p.config, p.hooks, ours);
const w = writeCodexSetupHooks(p.hooks, { want: groups, owned: new Set(ours.map((g) => g.hash)), preserve: new Set() });
for (const event of CODEX_EVENTS) {
const index = w.indexes[event];
if (index === undefined) return { action: 'refuse', path: p.hooks, detail: `${p.hooks} did not take the skill-resolver ${event} hook` };
const trust = codexSetupTrustEntry(p.hooks, event, index, groups[event]);
const existing = readCodexTomlTable(p.config, trustPath(trust.key)) as { trusted_hash?: unknown } | undefined;
if (existing === undefined) appendCodexTomlTable(p.config, trustPath(trust.key), { trusted_hash: trust.trusted_hash }, `gbrain setup (skill-resolver): trusts the skill-resolver lane ${event} hook; owned by its hash`);
else if (existing.trusted_hash !== trust.trusted_hash) return { action: 'refuse', path: p.hooks, detail: `${p.config} already has a different [hooks.state."${trust.key}"]; trust gbrain's skill-resolver hook in Codex's /hooks` };
}
return { action: 'write', path: p.hooks, detail };
}
/** Remove the lane's hook (and, on Codex, its trust entry). Throws on a file it cannot write safely. */
export function removeSkillResolverHook(opts: { harness: ResolverHarness; paths?: ResolverHookPaths; dryRun?: boolean }): ResolverHookOutcome {
const paths = opts.paths ?? {};
if (opts.harness === 'hermes') {
const o = removeHermesHook({ hermesHome: hermesHome(paths), lane: 'skill-resolver', dryRun: !!opts.dryRun });
return { action: o.action === 'remove' ? 'remove' : 'skip', path: o.path, detail: o.detail };
}
if (opts.harness === 'codex') {
const p = codexPaths(paths);
const ours = codexOurs(p);
if (ours.length === 0) return { action: 'skip', path: p.hooks, detail: `no skill-resolver hook in ${p.hooks}` };
if (!opts.dryRun) {
dropOurTrust(p.config, p.hooks, ours);
writeCodexSetupHooks(p.hooks, { want: {}, owned: new Set(ours.map((g) => g.hash)), preserve: new Set() });
}
return { action: 'remove', path: p.hooks, detail: `skill-resolver lane hooks from ${p.hooks} and their trust entries from ${p.config}` };
}
const path = claudePath(paths);
const ours = claudeOurs(path);
if (ours.length === 0) return { action: 'skip', path, detail: `no skill-resolver hooks in ${path}` };
if (!opts.dryRun) removeClaudeHooksAt(path, SKILL_RESOLVER_MARKER, { ownedEntryHashes: new Set(ours.map((o) => hookEntryHash(o.entry)).filter((h): h is string => !!h)) });
return { action: 'remove', path, detail: `skill-resolver lane hooks from ${path}` };
}